Headless CLI

zagens is Zagens’ headless command-line interface — the same agent runtime as the desktop app (the desktop embeds zagens-runtime; HTTP contract matches). Use it for scripts, CI, remote servers, and as the primary entry on macOS / Linux where no desktop installer ships yet.

Install steps: CLI install section on the public install guide.

vs desktop

	Desktop (Tauri)	CLI `zagens`
UI	WebView, sidebar, diff, replay	Terminal output
Platform	Windows 10/11 x64	Windows / macOS / Linux
Config	`~/.zagens/config.toml`	Same
Engine	Kernel V3 (local sidecar)	Kernel V3 (in-process runtime)

For a full-screen terminal UI on any OS, use zagens-tui — also Kernel V3, in-process (not covered on this page).

You can use both: desktop for daily work, CLI for automation.

Install and verify

# crates.io (Rust stable required)
cargo install zagens-cli --bin zagens --locked

# Or prebuilt from GitHub Releases
# https://github.com/didclawapp-ai/zagens/releases
# Windows: zagens-x86_64-pc-windows-msvc.exe

zagens --version
zagens doctor

API key

Any one of:

zagens login                    # writes ~/.zagens/config.toml
export DEEPSEEK_API_KEY=sk-...  # env var for the session

Set api_key, base_url, default_text_model, etc. in ~/.zagens/config.toml — see product repo config.example.toml.

Project overlay: .zagens/config.toml in the workspace (skip with --no-project-config).

Quick start

cd /path/to/your-repo

# Q&A without tools
zagens exec "Summarize README.md in three bullets"

# Agent mode: tools + shell (auto-approve — trusted CI only)
zagens exec "Run cargo test -p mycrate" --auto

# Machine-readable output
zagens exec "List main modules under src/" --json

# Explicit workspace (default: cwd)
zagens -w /path/to/repo exec "…"

Common global flags:

Flag	Role
`-w, --workspace`	Workspace root
`--config`	Config file path
`--profile`	Named config profile
`-v, --verbose`	Verbose logging
`--enable` / `--disable`	Toggle feature flags for one run

Command overview

Command	Purpose
`zagens doctor`	Environment and config diagnostics (`--json` skips live API probe)
`zagens doctor --tools`	Tool / harness telemetry (same as desktop Agent health)
`zagens login` / `logout`	Save / remove API key
`zagens models`	List models from configured endpoint (`--json`)
`zagens exec`	One-shot non-interactive prompt (`--auto` for tools)
`zagens review`	Code review over git diff (`--staged` / `--base`)
`zagens apply`	Apply a patch file or stdin
`zagens queue …`	Night queue: `add` / `list` / `run` / `briefing`
`zagens gate …`	Gate-as-Code: `validate` / `list`
`zagens skill drafts` / `promote`	List / promote `draft_skill` drafts
`zagens trace …`	Kernel Trace Report: `export` / `compare` / `serve` / `pack`
`zagens report harness`	Harness telemetry → markdown / Office
`zagens open-url`	Handle `zagens://open` deep links (`--validate-only`)
`zagens setup`	Bootstrap MCP / skills / tools templates
`zagens mcp …`	Manage MCP config (`list`, `tools`, `add`, …)
`zagens serve --http`	Local HTTP/SSE runtime API
`zagens sandbox …`	Windows: sandbox setup / teardown / add-read-dir
`zagens sessions`	List saved sessions
`zagens resume` / `fork`	Resume or fork a session (`--last`)
`zagens completions`	Shell completions
`zagens features list`	Feature flag state
`zagens eval`	Offline eval harness (no network)

Run zagens --help and zagens <cmd> --help for the exact build you installed.

`zagens exec`

zagens exec "Refactor auth and add tests" --auto
zagens exec "Explain config.rs" --model deepseek-v4-flash
zagens exec "Summarize changes" --json > out.json

Flag	Meaning
`--auto`	Agent mode: tools + shell with auto-approval (same tool surface as global `--yolo`)
`--json`	Structured JSON for CI parsers
`--model`	Override text model for this run

Safety: --auto may run shell and writes when policy allows. On Windows, complete Windows sandbox setup first; tighten sandbox_mode in CI — see Execution policy.

`zagens review` and `zagens apply`

zagens review --base origin/main
zagens review --staged
zagens apply fix.patch

review uses the same routing as desktop; cap diff size with --max-chars.

`zagens serve --http`

Exposes the same HTTP/SSE runtime API as the desktop sidecar (default 127.0.0.1:7878):

zagens serve --http --port 7878 --auth-token "$DEEPSEEK_RUNTIME_TOKEN"

Note	Detail
Current release	Only `--http` is supported (`--mcp` / `--acp` exit with an error)
Bind address	Defaults to localhost; use `--auth-token` if binding beyond loopback
Ready signal	Prints `DS_PICK_READY` JSON with port for probes

For local integration tests or custom orchestrators calling /v1/threads. Contract: product repo docs/tech/API_DESIGN.md.

`zagens setup` and MCP

zagens setup --all
zagens setup --mcp
zagens setup --skills
zagens setup --status

zagens mcp list
zagens mcp tools
zagens mcp validate

Desktop Settings → MCP shares ~/.zagens/mcp.json. See MCP servers.

Windows: `zagens sandbox`

Windows only — pairs with Windows sandbox:

zagens sandbox setup
zagens sandbox teardown
zagens sandbox add-read-dir D:\extra\read\path
zagens sandbox poc deny-read

zagens sandbox run … is not available in headless CLI yet; agent shell goes through runtime sandboxing on exec --auto.

Sessions

zagens sessions --limit 10
zagens resume <session-id>
zagens resume --last
zagens fork --last

Shares storage layout with desktop threads (DEEPSEEK_RUNTIME_DIR / default under ~/.zagens). Desktop session restore maps to resume / fork on CLI.

Environment variables

Variable	Role
`DEEPSEEK_API_KEY`	Provider API key
`DEEPSEEK_RUNTIME_TOKEN`	Auth for `serve --http`
`DEEPSEEK_CONFIG_PATH`	Override config path
`DEEPSEEK_RUNTIME_DIR`	Runtime data directory

CLI vs desktop

Scenario	Prefer
Daily coding, diff, replay, approval UI	Desktop
Full-screen terminal on macOS / Linux / Windows	`zagens-tui`
CI review or one-shot automation	`zagens exec` / `review`
Headless Linux server	CLI + optional `serve --http`
Office deliverables	Desktop Office mode
Schedules / night queue	Desktop Scheduled tasks · Night queue or `zagens queue`
Gate validation	`zagens gate validate` / `list` — Gate-as-Code

Night queue & gates (quick)

zagens queue add "fix failing tests" --gate-preset rust-cargo-smoke
zagens queue list
zagens queue run
zagens queue briefing --office

zagens gate list
zagens gate validate --preset rust-cargo-smoke --json
zagens doctor --tools --json

Limits

Desktop installer is Windows-only today; use zagens-tui or CLI on macOS and Linux.
zagens serve: only --http in this release.
zagens-tui is a separate binary — see Terminal TUI; it does not replace zagens exec.
Subcommands evolve per release — trust zagens --help on your binary.