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

!@ captures UTF-8 text as labelled file context and PNG, JPEG, GIF, or WebP files as images when you submit. Later edits or deletion do not change queued input. A prompt accepts up to 16 attachments and 1 MiB of combined content. Selection honors jail restrictions, and errors keep your input. Images require a vision-capable model. !@ is not expanded in slash-command arguments, shell commands, or noninteractive modes.

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, including its images, back into the editor.
[[@]]Open the file picker. Selected files insert path reference chips. Use right and left to browse directories.
[[!@]]Open the file picker to include a file's content instead of a path. Works in the main chat, /btw, and Swarm task and follow-up editors.
[[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.
image queueingPrompts with clipboard or !@ images can be submitted during an active turn. They run after it in submission order. Cancelling the turn discards pending prompts.
custom chordsUse keymap in config.json to bind modified chords to slash commands or to next / previous navigation actions in built-in lists and suggestion popups. Navigation bindings are opt-in, not default aliases. See TUI settings.