zev

Zev 🔍

[PyPI version] [License: MIT]

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

[Description]

🔧 Installation

Homebrew (macOS)

brew tap dtnewman/zev
brew trust dtnewman/zev
brew install zev

pipx (linux)

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:

1. Install and start Ollama with a model of your choice

2. 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.

1. Create a deployment of the model you want to use (e.g., gpt-5.4, gpt-5.4-mini etc.).

2. Install required Azure depedencies with pipx install zev[azure].

3. 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.