ai-cli

Converts natural-language to bash

Describe a task, get up to three candidate commands from a local (or remote) LLM, edit the best one inline, hit Enter to run it.

$ ai create ssh cert
task: create ssh cert
$ ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -C "$(whoami)@$(hostname)"
↑/↓ cycle  ·  ←/→ edit  ·  ⏎ run  ·  esc cancel    [1/3]

Works out of the box: it autodiscovers a running ollama, and if there is no LLM anywhere it offers to download a small self-contained one (~1.1 GB) so it keeps working fully offline.

Install

Grab a prebuilt binary from the releases page, make it executable and put it on your PATH.

Or build from source — requires only docker on the host:

./build.sh            # produces ./ai
./build.sh install    # also copies to ~/.local/bin/ai

Usage

ai <task in plain english> opens the interactive picker:

• ↑ / ↓ — cycle through the alternative suggestions
• ← / → / backspace — edit the current command
• Enter — run it in bash
• Esc / Ctrl-C — cancel

The suggestions are distinct alternatives (different tools or approaches), not sequential steps — each one accomplishes the whole task on its own.

As you cycle and edit, the command is parse-checked in-process (via mvdan.cc/sh, nothing is executed); a ⚠ syntax error … line appears when it isn't valid bash. Running is never blocked — you can still run or fix it.

For scripts and pipes, ai --print <task> skips the UI and prints the suggestions one per line.

Providers

Configuration is resolved in this order — the first source that yields a provider wins:

1. Env vars (see table below) override everything.
2. The config file ~/.config/ai/config.json, written by ai --setup.
3. Autodiscovery: an ollama at OLLAMA_HOST, localhost:11434 or 127.0.0.1:11434 that serves at least one model; otherwise a previously downloaded built-in local model.
4. Nothing found → the first-run offer to download the local model.

ai --setup walks through the three options interactively:

• ollama — local or remote, picks the first installed model by default
• OpenAI-compatible endpoint — OpenAI, Groq, OpenRouter, vLLM, a remote ollama, … (base URL must include /v1)
• built-in local model — no server needed, see below

The built-in local model

If no ollama is serving a model and no API key is set, ai asks once whether to download a self-contained setup into ~/.local/share/ai:

• llama.cpp release b10107 (prebuilt, ~16 MB) — linux/macOS, amd64/arm64
• Qwen2.5-Coder-1.5B-Instruct Q4_K_M (~1.07 GB)

Both are pinned by sha256 and verified before use. Interrupted downloads resume. Nothing is downloaded without confirmation; ai --pull does it up front.

There is no daemon. Each run execs llama-completion once, which mmaps the model, answers, and exits — roughly 2.5 s warm on an 8-core laptop. Output is constrained by a JSON grammar, so the command list can't come back malformed.

Caveats worth knowing:

• A 1.5B model is visibly weaker than an 8B: expect placeholders like your_email@example.com, rsa instead of ed25519, and sometimes one suggestion instead of three. Read the command before pressing Enter.
• The prebuilt engine needs libssl3, libstdc++6 and libgomp1. Present on a normal desktop; missing on slim containers, where --pull says so explicitly.

Configuration

Config lives at ~/.config/ai/config.json. Everything can also be set by env var (env wins over the config file):

var	meaning	default
AI_PROVIDER	ollama, openai or local	autodiscover
AI_BASE_URL / OLLAMA_HOST	endpoint base URL	http://localhost:11434
AI_API_KEY / OPENAI_API_KEY	bearer token (openai)	—
AI_MODEL	model name, or a .gguf path when local	first local model / gpt-4o-mini
AI_DATA_DIR	where the local engine + model live	~/.local/share/ai

Flags

ai <task>           # interactive picker
ai --print <task>   # print suggestions, no interactive UI (scriptable)
ai --setup          # (re)configure the provider
ai --pull           # download the local engine + model now (offline use)
ai --help