Quickstart

Install zot and run your first session.

Docs on GitHubView Markdown

Install

macOS and Linux:

shell
curl -fsSL https://www.zot.sh/install.sh | bash

Windows (PowerShell):

powershell
iwr -useb https://www.zot.sh/install.ps1 | iex

With Go:

shell
go install github.com/patriceckhart/zot/cmd/zot@latest

Log in

Use /login to store an API key or a subscription credential. zot supports Claude Pro/Max, ChatGPT/Codex, Kimi Code, SuperGrok/X Premium, and GitHub Copilot subscriptions, plus direct API keys for every provider in the catalog. See Providers for browser, pasted-code, and device-code login options.

Note on subscription login

The OAuth client IDs used are the ones published in the official CLIs. Reusing them from a third-party tool may be against their terms of service and may be revoked at any time. The API-key flow is the safe default.

Or use local Ollama without login

With Ollama already running, install a model and select it explicitly:

shell
ollama pull qwen3.5:4b
zot --provider ollama --model qwen3.5:4b

No API key, config.json, or models.json is required for this command. zot defaults to http://localhost:11434. See Settings to save the default selection and Models for remote servers or the same model on multiple hosts.

Run it

shell
zot # interactive TUI
zot -p "summarize this repo" # one-shot to stdout
cat README.md | zot -p "summarize this text" # combine stdin with the prompt
zot -p --stats stats.json "summarize this repo" # one-shot plus generation stats
zot --json "run the tests" # NDJSON events

Pick a model with /model, set its reasoning level with /reasoning, confine tools for the current session with /jail, or enable jail new sessions by default in /settings to start future sessions jailed. Resume your last session with zot -c. Slash command names are case-insensitive, while arguments such as model IDs and paths preserve their original casing.

In print, stream, and JSON modes, piped stdin is prepended to the positional prompt with a newline separator. This lets shell pipelines provide the source text while the positional argument supplies the instruction.

Print-mode statistics

Use --stats PATH with -p or --print to write generation statistics to a JSON file while keeping stdout limited to the final assistant text. The file is written only after a successful run.

stats.json
{
  "provider": "openai",
  "model": "gpt-5",
  "prompt_tokens": 123,
  "reasoning_tokens": 45,
  "generated_output_tokens": 18,
  "elapsed_ms": 1234
}

Counts cover every model turn triggered by the prompt, including tool loops. Prompt tokens include cache reads and writes. reasoning_tokens is null when the provider does not report a separate count; in that case generated_output_tokens is the provider's total output count and may include reasoning. Elapsed time covers the agent run, not startup or credential resolution.

Input navigation

KeyAction
[[up]] / [[down]]Move within multi-line input. At the top edge, up recalls previous prompts and down moves forward through prompt history.
[[up]] / [[down]] with empty inputScroll the chat when you are not browsing prompt history.
[[alt+up]]Move the most recent queued message back into the editor.
[[ctrl+v]]Paste clipboard text into the focused chat, side chat, dialog, filter, or credential input. In the main chat, image clipboard content is attached to the next prompt on macOS, Windows, Linux Wayland with wl-paste, and Linux X11 with xclip. Linux text paste also supports xsel. Terminal-native paste works without those commands.
mouse click / drag (opt-in)Enable click to position cursor under /settings > tui settings. Click in the input to move its cursor. Drag visible text to select it, then use ctrl+c to copy or esc to dismiss. Selection persists after release and is not copied automatically. See TUI settings.
custom chordsBind ctrl, alt, shift, or cmd chords to any slash command with keymap in config.json. See TUI settings.