# zev: a command line that describes what you want done

> zev is a small Python CLI that turns a sentence into a terminal command, using OpenAI, Gemini, Azure OpenAI, or a local Ollama model. It runs interactively or takes a query directly, keeps the answer in the clipboard, and warns about dangerous commands, while its own documentation is careful to say that the warning is not a guarantee.

**dtnewman/zev** — A simple CLI tool to help you remember terminal commands

- Repository: https://github.com/dtnewman/zev
- Stars: 722 · Forks: 47
- Language: Python
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/dtnewman-zev

## Describing the task instead of recalling the syntax

zev is a simple command line tool to help you remember terminal commands, and the README states the purpose in one sentence: it helps you remember, or discover, terminal commands using natural language.

The idea is small and it works because the hard part of a command line is not the intent but the syntax. A person who knows they want to see the disk usage of the current directory still has to remember which flag, which subcommand, and in which order. zev closes that gap by asking the model and putting the result in the clipboard.

There is a demo animation in the repository, and the PyPI badge and the topics show where the project sits: it is a command line tool, and it is built on a language model.

The licence is MIT, the last push was on 2026-06-17, and the repository has no GitHub releases, so the distribution channel is the package index and the Homebrew tap rather than a tagged artefact.

The package version in the project metadata is 0.11.1, and the description there is a little more functional than the README, lookup CLI commands easily, which is a fair summary of the whole thing.

## Installing, and the clipboard on Linux

There are two supported install routes, one per platform, and both are short.

On macOS, Homebrew, with a tap of the repository and then the install.

```bash
brew tap dtnewman/zev
brew trust dtnewman/zev
brew install zev
```

The README lists this trust step as part of the install, because the formula lives in a tap of the repository rather than in Homebrew core.

On Linux, pipx, which installs the tool into its own environment rather than into the system Python, which is the right choice for a command line application.

```bash
pipx install zev
```

The dependency note is the part that trips people up. The project runs on top of LLM APIs, with OpenAI, Google Gemini, and Ollama named as the options, and for the clipboard functionality to work properly there may be extra tools to install.

On Linux that is xclip or xsel for X11, or wl-clipboard for Wayland. On macOS no additional dependencies are needed, and on Windows no additional dependencies are needed either.

That is a small detail with a real symptom. On a bare Linux system the tool installs cleanly and then the copy step does nothing, and the natural conclusion is that the tool is broken rather than that a clipboard utility is missing.

## Two ways to use it

There is an interactive mode and a direct query, and the difference is whether the tool asks you for the question.

```bash
zev
```

```bash
zev '<what you want to do>'
```

The examples in the README show the range of things people ask, and they are ordinary shell tasks rather than exotic ones.

```bash
# 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'
```

There is a practical reason for the direct form, which is scriptability. A query in a shell script, or in a shell alias, becomes a command generator that is available without a person in the loop, and that is a different tool from the interactive one even though the code is the same.

The commands themselves are not run by zev. The tool produces the command and puts it in the clipboard, and the person or the script decides what to do with it. That distinction is the safety model, and the next section is about how far that model goes.

## The safety warning, and what it does not promise

There is a section on safety considerations, and it is short enough to quote.

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

The repository has an image of the dangerous command warning, so the detection is implemented and visible in the interface. What the documentation is careful about is the limit of it. The tool is not a sandbox and it is not a policy engine, it is a best effort classifier running on the output of a model that was asked to write a shell command.

That is the single most important thing to understand about the tool, and it is the reason the answer is in the clipboard rather than executed directly. A generated command that you read is a suggestion you can check. A generated command that runs itself is a different proposition, and the design deliberately stops short of it.

The caveat is also version dependent in a practical way. A model asked for a command will produce a plausible command, and plausible is not the same as correct, and a plausible command with a destructive flag is the failure case that matters. The examples in the README are benign, but the question asked of the model is the same either way.

So the sensible use is the one the tool implies. Ask, read, adjust, run. And treat the warning as a useful signal rather than as a guarantee.

## Four providers, and running entirely on Ollama

The settings section lists four supported providers: OpenAI, Google Gemini, Ollama, and Azure OpenAI. The API keys and the provider configuration are managed through a setup command, and you can run it again at any time to switch backends.

```bash
zev --setup
```

OpenAI needs an account and a subscription, and the key comes from the platform settings page. Gemini is described as free and needs a Google AI Studio account, with the key created there.

Ollama is the one that changes the privacy picture, because it lets all the commands be run locally. The setup is to install and start Ollama with a model of your choice, then run the setup command and give it the URL and the model name.

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

The OpenAI compatible endpoint that Ollama exposes is why the same code path works for both, and the setup prompt style, with the question marks and the colon, is the questionary library in the dependency list.

Azure OpenAI needs a resource in the Azure subscription and a deployment of the model, plus an extra dependency installed with the azure extra. The setup asks for the account name, the API key, which can be left blank to use Entra ID with keyless authentication, the deployment name, and the API version. Two version floors are stated in the notes, the model version must be 2024-08-06 or newer and the API version must be 2024-08-01-preview or newer.

## The package behind the tool

The project metadata is short, and each dependency corresponds to a visible part of the tool.

The OpenAI client is the transport, and it is the only provider specific dependency, because the other three are reached through compatible interfaces. The questionary library is the interactive prompt, and rich is the formatted output. Pydantic is there for the settings and the response models, python-dotenv reads the environment, and platformdirs finds the configuration directory in the right place on each operating system. Pyperclip is the clipboard.

The console script is a single entry point, and the package requires Python 3.9 or newer. The optional groups are small: a development group with the linter and the import sorter, and an Azure group with the identity library for the keyless path.

The linting configuration is narrow on purpose. The line length is 120 and the only selected rule is the import sorting one, with the isort configuration set to the black profile so the two tools agree.

The repository layout is the usual for a modern Python package: the sources under src, a scripts directory, a Formula directory holding the Homebrew formula, a lock file for the development environment, and the usual project files including a contributing guide and a file with instructions for an assistant, which says something about how the project expects to be worked on.

There are no GitHub releases, so the version history for a user is the package index, and the version in the metadata is the one to pin against if you are installing it as a tool in a reproducible environment.

## Conclusion

zev fits a developer who remembers roughly what a command should do but not its exact flags, or who is learning a tool whose command line syntax is unfamiliar, and who is comfortable sending a description of the task to a model provider. It does not fit a shell that cannot reach a hosted API, unless Ollama is available locally, and it does not fit a workflow where a generated command is run without being read. Verify first that the provider you configure can reach the kind of query you intend to ask, that the clipboard utility is present on a Linux desktop since the copy and paste behaviour depends on it, and that the dangerous command warning is treated as a hint rather than as a guarantee, because the documentation says in as many words that the tool may not flag every risky command.

## FAQ

### What does zev do?

It turns a description of a task in natural language into a terminal command, so you can ask for running processes, recent file modifications, disk usage, or uncommitted git changes, and copy the result. It runs interactively with no arguments, or takes a query directly as an argument.

### How do I install zev?

On macOS with Homebrew, by tapping the repository, trusting the tap, and installing the package. On Linux with pipx, which is pipx install zev. For the clipboard to work on Linux you also need xclip or xsel for X11, or wl-clipboard for Wayland, while macOS and Windows need nothing extra.

### Can zev run without sending anything to a hosted provider?

Yes, by using Ollama. You install and start Ollama with a model, then run zev --setup and give it the Ollama URL, which is the local OpenAI compatible endpoint, and the model name. The setup command can be run again at any time to switch backends.

### Does zev run the commands it generates?

No, it produces them and puts them in the clipboard. The documentation is also explicit that the commands are generated by a language model and that while the tool tries to flag dangerous commands it may not always do so, so the warning should be treated as a hint rather than a guarantee.

### Which LLM providers does zev support?

OpenAI, Google Gemini, Ollama, and Azure OpenAI. The Azure path needs an extra dependency installed with the azure extra, a deployment of the model, and two version floors, with the model version to be 2024-08-06 or newer and the API version to be 2024-08-01-preview or newer.

## Sources

- [dtnewman/zev on GitHub](https://github.com/dtnewman/zev)
- [Issues](https://github.com/dtnewman/zev/issues)
- [License: MIT](https://github.com/dtnewman/zev/blob/main/LICENSE)
- [README](https://github.com/dtnewman/zev/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dtnewman-zev