Zev 🔍

Zev helps you remember (or discover) terminal commands using natural language.

Description

🔧 Installation

Homebrew (macOS/Linux)

brew tap dtnewman/zev
brew install zev

pip

pipx install zev

Note: This project runs on top of LLM APIs like OpenAI, Google's Gemini, or Ollama.

📦 Dependencies

For clipboard functionality (copying and pasting) to work properly, you may need to install:

On Linux: xclip or xsel (for X11) or wl-clipboard (for Wayland)
On macOS: No additional dependencies needed
On Windows: No additional dependencies needed

🎮 Usage

Option 1: Interactive Mode

zev

Option 2: Direct Query

zev '<what you want to do>'

📝 Examples

# Find running processes
zev 'show all running python processes'

# File operations
zev 'find all .py files modified in the last 24 hours'

# System information
zev 'show disk usage for current directory'

# Network commands
zev 'check if google.com is reachable'

# Git operations
zev 'show uncommitted changes in git'

🛡️ Safety Considerations

⚠️ Commands are generated by LLMs. While the tool attempts to flag dangerous commands, it may not always do so. Use caution.

Example of dangerous command warning

⚙️ Settings

Supported LLM Providers:

OpenAI
Google Gemini
Ollama
Azure OpenAI

You can update your API keys and provider settings by running:

zev --setup

OpenAI

To use OpenAI, you need an OpenAI account and a subscription. You can create an API key on this page.

Google Gemini (Free)

To use Google's Gemini models, you need a Google AI Studio account. You can create a Gemini API key in Google AI Studio.

🐪 Using with Ollama

You can use Zev with Ollama as an alternative to hosted providers, which lets you run all commands locally. To set this up:

Install and start Ollama with a model of your choice
Run zev --setup and put in the proper settings. For example:

? Pick your LLM provider: Ollama
? Enter the Ollama URL: http://localhost:11434/v1
? Enter the model to use (e.g. llama3.2): llama3.2

Azure OpenAI

To use Azure OpenAI, you’ll need access to an Azure OpenAI resource in your Azure subscription.

Create a deployment of the model you want to use (e.g., gpt-5.4, gpt-5.4-mini etc.).
Install required Azure depedencies with pipx install zev[azure].

Run zev --setup and put in the proper settings. For example:

? Pick your LLM provider: Azure OpenAI
? Azure OpenAI account name (e.g. my-openai-resource): my-openai-resource
? Azure OpenAI API key (leave blank to use Entra ID / keyless auth):
? Azure OpenAI deployment name (e.g. gpt-5.4, gpt-5.4-mini, etc): gpt-5.4-mini
? Azure OpenAI API version: 2025-03-01-preview

Note: Model version must be 2024-08-06 or newer.
API version must be 2024-08-01-preview or newer.

Note that to switch backends, you can re-run zev --setup again at any time.

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Release files for zev 0.11.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zev 0.11.1
File	Size	Uploaded
zev-0.11.1.tar.gz	15.6 kB	Apr 21, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for zev 0.11.1
File	Interpreter	ABI	Platform	Reset
zev-0.11.1-py3-none-any.whl 19.8 kB Apr 21, 2026	Python 3	none	any	Details

Total release size: 35.4 kB

Release files / zev-0.11.1.tar.gz

Download URL	zev-0.11.1.tar.gz
Size	15.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`b6a53a1f3de005fb94a307595084f2c5e34cc47b4a5589fd1779ecc8b498df4a`
BLAKE2b-256 checksum How to use checksums	`97b40703ba4fe7b45d122c3418684758181cc425385666f47351c6640c9ee24c`
Upload date	Apr 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/dtnewman/zev
Publishing commit: github.com/dtnewman/zev/tree/3fb3625d211138b4600bd457fd87a80171e553a2

Workflow

Publishing configuration: github.com/dtnewman/zev/blob/3fb3625d211138b4600bd457fd87a80171e553a2/.github/workflows/publish.yml
Publishing logs: github.com/dtnewman/zev/actions/runs/24702454000/attempts/1

Artifact

Subject: zev-0.11.1.tar.gz
SHA-256 checksum: b6a53a1f3de005fb94a307595084f2c5e34cc47b4a5589fd1779ecc8b498df4a Verifying attestations

Release files / zev-0.11.1-py3-none-any.whl

Download URL	zev-0.11.1-py3-none-any.whl
Size	19.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`96a7fe70c59299a83038db191f015ba7697ae0e37a6db30ab57632a913908bea`
BLAKE2b-256 checksum How to use checksums	`4f2d2f9143aeaf99779d6bb833656f1174d43f16805a58e60170946a12772bb5`
Upload date	Apr 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/dtnewman/zev
Publishing commit: github.com/dtnewman/zev/tree/3fb3625d211138b4600bd457fd87a80171e553a2

Workflow

Publishing configuration: github.com/dtnewman/zev/blob/3fb3625d211138b4600bd457fd87a80171e553a2/.github/workflows/publish.yml
Publishing logs: github.com/dtnewman/zev/actions/runs/24702454000/attempts/1

Artifact

Subject: zev-0.11.1-py3-none-any.whl
SHA-256 checksum: 96a7fe70c59299a83038db191f015ba7697ae0e37a6db30ab57632a913908bea Verifying attestations