aiterm translates natural language into shell commands, right in your terminal.
Describe what you want, review the command it suggests, then run it, copy it, edit it,
or refine it with a follow-up request. No more searching for that find or tar
incantation.
It is written in Go, ships as a single binary, and works with OpenAI or any OpenAI compatible API, including local models served by Ollama or LM Studio.
- Natural language to commands: describe the task, get a single command tailored to your OS (macOS BSD tools or Linux GNU tools).
- You stay in control: nothing runs until you press
y. You can also copy the command, edit it before running, or exit. Replies that hide characters from the terminal are refused, and multi line commands are flagged before you confirm. - Follow-up requests: refine the last answer with context ("now include hidden files") or start fresh without it.
- Bring your own model: pick any model with
-model, including reasoning models, and point-urlat any OpenAI compatible endpoint (Ollama, LM Studio, OpenRouter, ...). - Single static binary for Linux and macOS on amd64 and arm64.
Download the archive for your platform from the
latest release, extract it and put
aiterm on your PATH. For example:
# macOS on Apple silicon (use Darwin_x86_64 for Intel Macs)
curl -fsSL https://github.com/Thakay/aiterm/releases/latest/download/aiterm_Darwin_arm64.tar.gz | tar -xz aiterm
sudo mv aiterm /usr/local/bin/
# Linux on x86_64 (use Linux_arm64 for ARM)
curl -fsSL https://github.com/Thakay/aiterm/releases/latest/download/aiterm_Linux_x86_64.tar.gz | tar -xz aiterm
sudo mv aiterm /usr/local/bin/To verify a download, fetch the archive and checksums.txt from the release, then run
sha256sum --ignore-missing -c checksums.txt (on macOS:
shasum -a 256 --ignore-missing -c checksums.txt).
The release archives include the aiterm(1) manual at
docs/aiterm.1. Install it in your system's man1 directory to read it
with man aiterm.
Requires Go 1.26 or newer. Go 1.21 and later download the right toolchain automatically.
go install github.com/Thakay/aiterm@latestgit clone https://github.com/Thakay/aiterm.git
cd aiterm
go build -o aiterm .Completion scripts for bash, zsh and fish live in completions/ and are
included in the release archives. They complete the flag names; -timeout
also suggests a few durations. Everything after the flags is the request,
so there is nothing to complete there.
For bash, copy the script into your completion directory and start a new shell:
sudo cp completions/aiterm.bash /etc/bash_completion.d/aitermOn macOS with Homebrew the directory is /usr/local/etc/bash_completion.d/
(or /opt/homebrew/etc/bash_completion.d/ on Apple silicon).
For zsh, copy the script as _aiterm into a directory on your fpath:
mkdir -p ~/.zsh/completions
cp completions/_aiterm ~/.zsh/completions/
autoload -Uz compinit && compinitFor fish, copy the script into your completions directory:
cp completions/aiterm.fish ~/.config/fish/completions/aiterm needs an API key. Flags go before the request and take precedence over
environment variables.
| Flag | Environment variable | Default | Description |
|---|---|---|---|
-key |
OPENAI_KEY |
API key sent as a bearer token | |
-model |
AITERM_MODEL |
gpt-4.1-mini |
Model used to generate commands |
-url |
AITERM_URL |
https://api.openai.com/v1/chat/completions |
Chat completions endpoint of an OpenAI compatible API |
-timeout |
AITERM_TIMEOUT |
2m |
How long to wait for the API, such as 30s or 5m |
-print |
Print the suggested command to stdout and exit | ||
-version |
Print the version and exit |
Prefer the environment variable over -key, so the key does not end up in your shell
history or the process list. Set it in your shell profile (~/.zshrc, ~/.bashrc),
or enter it without echo for the current shell with read -rs OPENAI_KEY && export OPENAI_KEY.
If no key is set, or the key is rejected, aiterm asks for one (without echoing it)
and uses it for the current session.
-print skips the menu: it writes the suggested command, and nothing else, to stdout
and exits. Nothing runs and nothing is read from stdin, so a missing or rejected key, a
reply that is not a command, or a reply with hidden characters exits with code 1 and
a message on stderr instead of prompting.
aiterm -print "find files larger than 100 MB"
# find . -type f -size +100MPiping the output straight into a shell (aiterm -print ... | sh) skips the
confirmation step entirely, so only do that if you trust the reply without reading it.
Putting it on your command line to edit first is the safer pattern, e.g. in zsh:
print -z -- "$(aiterm -print 'list all go files')".
export AITERM_URL="http://localhost:11434/v1/chat/completions"
export AITERM_MODEL="llama3.2"
export OPENAI_KEY="ollama" # Ollama ignores the key, but aiterm expects one to be set
export AITERM_TIMEOUT="5m" # optional: give slow local models more timeFor common failures, aiterm keeps the original error and prints a next step: check the model for a 404 or model_not_found, check billing for insufficient_quota, wait and retry for other 429 responses, and retry later for 5xx responses. A connection refusal at a localhost or loopback URL suggests starting the local server. Other errors receive no hint, and rejected API keys keep their existing handling.
The full command reference is in the aiterm(1) manual page.
Pass your request as arguments. Quotes are optional for plain words, but your shell
expands the arguments before aiterm sees them, so quote the request if it contains
characters such as *, ?, &, |, ;, <, >, #, $ or an apostrophe.
Single quotes are the safest choice.
aiterm "find all the files that contain the word foo in the parent directory"
aiterm show the 10 largest files in this folder
aiterm 'list *.log files older than 7 days'aiterm shows the suggested command and a menu:
| Key | Action |
|---|---|
y |
Run the command (its output streams straight to your terminal) |
c |
Copy the command to the clipboard and exit |
g |
Copy the command, then paste an edited version to run with aiterm |
r |
Send a follow-up request that keeps the conversation context |
w |
Send a new request without the previous context |
q |
Quit |
If a command fails, or you stop it with Ctrl+C, aiterm prints the exit status and
brings the menu back so you can edit it or ask for another one.
On Linux, copying to the clipboard needs xclip, xsel or wl-clipboard. Without
one of them, aiterm prints the command so you can copy it yourself.
Warning
Commands come from a language model and can be wrong or destructive. Always read a
command before you run it. aiterm refuses replies containing control or invisible
characters (which could make the terminal show something other than what runs) and
warns when a command spans several lines.
make test # go test -race ./...
make lint # golangci-lint run (https://golangci-lint.run)
make fuzz # fuzz the model reply validation
make snapshot # build the release archives locally with GoReleaserThe tests cover about 96% of the statements and never call a real API: they use a
scripted fake provider and an httptest server. Every pull request runs the tests on
Linux and macOS with the two supported Go releases, plus fuzzing, golangci-lint,
CodeQL, govulncheck and a GoReleaser snapshot build. Releases are built by
GoReleaser when a v* tag is pushed. See
CONTRIBUTING.md for details.
- An explain option that describes what a command does before you run it (#5)
- Anthropic and Gemini models (#6)
- Windows support with PowerShell commands (#7)
- A Homebrew tap (#8)
Issues labeled good first issue are a good place to start. Ideas and feedback are welcome in the issue tracker.
Contributions are welcome! Please read CONTRIBUTING.md and our Code of Conduct before opening a pull request. Report security issues privately as described in SECURITY.md.
SAKO, by the same author, is a task ledger and finish gate for coding agents such as Claude Code and Codex.
aiterm is licensed under the MIT License.
For questions and support, open an issue.