Command line reference

Ziro installs a single console script, ziro, which is the same entry point as python -m ziro_cli.main. Everything else is a module you run with python -m.

The main entry point

ziro

python -m ziro_cli.main

Subcommands

Command	What it does
`ziro`	Start a chat session. First run walks the setup wizard, then the user, flavour, thread, and agent pickers.
`ziro setup`	Re-open the setup wizard even when a key is already configured, to re-key, switch model, or switch theme. Fields are prefilled.
`ziro upgrade`	Install the newest release from the index (`ZIRO_PYPI_HOST`, default `test.pypi.org`) into its own environment and switch to it. `--version <v>` pins one, `--list` shows what is installed, `--rollback` returns to the previous version.
`ziro plugin …`	Install and manage plugins and marketplaces. See plugin CLI.
`ziro agents …`	Alias for `python -m ziro_cli.cli.manage_agents`. See manage agents.
`ziro init`	Scaffold a project, optionally seeded from a flavour with `--flavour`.
`ziro config doctor`	Check every config file Ziro reads (project, user and bundled layers) and list each problem with its file, line and runtime effect. Read-only. `--project <dir>` checks another project, `--json` prints JSON. Exits 1 on any error. See Validating config.
`ziro migrate-config`	Fold an agent’s legacy split `_policy.yaml` files into a single `settings.yaml`. `--path <dir>` targets one agent dir, `--dry-run` reports what would fold without writing, `--delete` removes the `.migrated` backups. Resolution is unchanged before and after. See Configuration.

ziro setup and ziro flavour strip their subcommand and keep parsing the normal flags, so ziro setup --theme nord works.

Flags

All of these apply to ziro and python -m ziro_cli.main equally.

string

User ID. Scopes long-term memory. Omit it to reuse the last-used user, or to get the first-run picker.

string

Agent ID to run. Omit it to pick interactively. An agent that is disabled, or that falls outside the active flavour, is rejected or corrected to the flavour’s default agent.

string

Flavour to launch. Scopes which agents are visible, which threads exist, and which shared memory is used. Omit it to pick interactively when several are configured, or to resume the last one. Bundled flavours are chat, development, engineering, research, and safe.

string

Thread ID to resume a previous session. Alias: --resume.

boolean

default:"false"

Force the plain rich REPL instead of the Textual TUI.

boolean

default:"false"

Enable push-to-talk voice I/O. Requires the agent’s voice section (was voice_policy.yaml) to have enabled: true. Implies the rich REPL.

string

Headless: run one turn and print the reply, then exit. -p "message" sends that message; a bare -p reads the message from stdin.

boolean

default:"false"

With -p, emit the chat_once JSON line instead of plain text.

path

Path of a file to attach to the first message. Repeatable. May point outside the project (media only there). A model that cannot take that kind of media receives a text stub naming the file instead. See File references.

string

UI theme name for this launch, overriding the saved preference. Bundled themes are ziro (the default), carbon, nord, and gruvbox.

path

Load a plugin for this session only: a plugin folder, or a .zip that holds one. Repeatable. The plugin loads as inline/<hash>/<name>, replaces an installed plugin with the same name for the session, and is not trusted: its hooks, stdio and remote MCP servers stay off until you run /plugins trust <id>. A path that is not a plugin, or that holds a : (or ; on Windows), is refused with exit code 2. The flag is read by the chat session only; ziro plugin ... honours the ZIRO_PLUGIN_DIRS variable instead. See Try a plugin for one session.

string

Seed the reasoning effort for this session: high, medium, low, or off. Change it live with /think.

Which front end you get

The entry point picks one of three front ends. The rule is short:

-p is present

Run exactly one turn headless, print the reply (or the JSON line with --json), and exit. Textual is never imported. The wizard and pickers never run: the user is resolved from --user or the last-used user, and a missing user or missing API key fails fast to stderr.

A TTY with Textual available

Launch the Textual TUI. The shell paints in roughly 1.6 seconds and is usable immediately; anything you type before the engine finishes building is queued and runs in order once it is ready.

Anything else

Fall back to the rich REPL. This is also what --no-tui and --voice force, and what you get when Textual is not installed or stdout is not a terminal.

The TUI is import-guarded. No Textual, or no TTY, degrades to the REPL rather than failing.

Examples

# First run: wizard, then pickers, then chat
ziro

# Start a specific agent for a specific user
python -m ziro_cli.main --user alice --agent researcher

# Scope the session to a flavour
python -m ziro_cli.main --user alice --flavour engineering

# Resume a thread
python -m ziro_cli.main --user alice --thread 3f2a91c4

# Force the rich REPL
python -m ziro_cli.main --user alice --no-tui

# One headless turn, plain text
python -m ziro_cli.main --user alice -p "summarize today's notes"

# One headless turn, JSON on stdout
python -m ziro_cli.main --user alice -p "list open todos" --json

# Read the message from stdin
echo "what changed in the last commit?" | python -m ziro_cli.main --user alice -p

# Attach images to the first message
python -m ziro_cli.main --user alice --attach diagram.png --attach chart.png

Other entry points

Entry point	What it does
`python -m ziro_cli.cli.chat_once`	Single-shot JSON invocation, plus the background job queue via `--submit` and `--status`. See chat-once.
`python -m ziro_cli.cli.manage_agents`	List, scaffold, remove, enable, disable agents and subagents; set the default agent and per-agent models. See manage agents.
`python -m ziro_cli.cli.run_scenarios`	Replay the scenario files in `tmp/`.
`python -m ziro_cli.cli.show_graph`	Visualize the LangGraph state machine. ASCII by default; `--format mermaid` or `--format png`.
`python -m ziro_cli.cli.startup`	Pre-cache the embeddings model, spaCy, and the Llama Guard models so later launches can run Hugging Face offline.
`python -m ziro.rag.indexer <path>`	Index documents into the `docs` collection. Accepts a directory, a `.txt`, or a `.pdf`.
`python -m ziro.tools.indexer`	Re-index tool descriptions into the `tools` collection.
`python -m ziro.skills.loader`	Index every `SKILL.md` in the skill roots into the `skills` collection.
`python -m ziro_cli.tui.demo`	Scripted TUI demo on a torch-free fake runner. `textual serve "python -m ziro_cli.tui.demo"` serves it in a browser.

Supporting commands

uv sync                          # install dependencies
uv sync --group voice-local      # add faster-whisper STT and Piper TTS
mypy .                           # type check
docker compose up -d             # PostgreSQL + pgvector (prod mode)
docker compose up -d searxng     # optional SearXNG backend for web_search
docker compose build pdf-sandbox # build the image for shell `mode: sandbox`

Dev and prod modes

The runtime mode is selected by one environment variable, not a flag.

`DATABASE_URL`	Store	Checkpointer	Vectors
Unset	`SqliteStore` at `./data/memories.db`	`AsyncSqliteSaver` at `./data/checkpoints.db`	FAISS
Set	`PostgresStore`	`AsyncPostgresSaver`	PGVector

See environment variables for the full list.

Next steps

Slash commands

Everything you can do once a session is running.

Headless runs

The -p and --json contracts in detail.

Environment

Keys, providers, model tiers, and the runtime switches.