CLI Reference

This page helps you find the exact command and flag you need.

Verified against packages/runtime/src/cli-app.ts. Run jazz <command> --help for the same information at the terminal.

Global options

Available on every command.

jazz

With no arguments, launches the interactive wizard — new conversation, create/list/edit/delete agents, update configuration. The home screen reports what is ready under setup (agents) and, under environment, the same machine facts every agent receives in its system prompt: date, OS with shell and user, working directory, and hardware. Both come from one source, so the screen cannot drift from what agents are actually told. On a short terminal the environment report is the first section dropped, after the tip.

jazz run — headless, one-shot

The command every non-terminal integration is built on. Takes a dynamic prompt, runs one agent turn, prints a clean payload. stdout is the answer; all chatter goes to stderr.

jazz run --agent <id> [prompt]

The prompt comes from the positional argument, or from piped stdin when the argument is absent and stdin is not a TTY.

--max-cost-usd, --max-tokens, and --max-duration-ms are soft checkpoints, not preemptive interrupts — see Configuration → maxCostUSD, maxTokens, and maxDurationMs for the enforcement model and how they differ from --timeout.

Exit codes: 0 on success, 1 on failure. In plain mode stdout is empty on failure and the message goes to stderr; in --json mode stdout always carries exactly one object.

Full contract, examples, and a complete bridge implementation: Surfaces → Headless.

jazz agent

agent chat accepts --stream / --no-stream and --max-iterations <n>.

jazz workflow

jazz workflow run flags

Frontmatter fields: Workflow frontmatter.

jazz mcp

See Integrations → MCP.

jazz runs

Inspect runs still in flight — including your own parked ones, and, once a daemon started one, runs begun from somewhere else entirely.

A run parks when it hits something needing your approval and nobody is there to give it — see Daemon for answering one from a different process than the one that started it.

jazz daemon

Serves runs over HTTP: start one, poll it, approve or reject what a parked one is waiting for — from a different terminal, a different process, or a different machine than the one that began it. Runs in the foreground; supervision (restart on crash, start on boot) is the host’s job, not the daemon’s — jazz daemon install wires it into that supervisor (systemd/launchd) instead of leaving that hand-written.

A bearer token authenticates the operator routes (/runs, /health) whenever --host is anything but loopback; loopback needs none. The first time this daemon binds a non-loopback host with no token already set, Jazz generates one and stores it — an OS keyring when one’s reachable, otherwise a chmod 600 file at $JAZZ_HOME/secrets.json (see Setting up peers) — printing it once so it can be copied to a client. No setup command required. /peer/ask (when --serve-peers is given) uses a separate, per-peer credential instead — see jazz peers.

Set $JAZZ_DAEMON_TOKEN yourself instead of letting Jazz generate one when the value needs to be known ahead of time — a client config written before the daemon has ever run, or an ephemeral container whose $JAZZ_HOME doesn’t survive to the next deploy.

See Setting up peers for a full walkthrough, and Agent-to-agent for the tier model this exists to serve.

jazz wake-trigger fire --agent <agentId> --id <id> is internal plumbing, not something you run by hand: it’s what register_trigger schedules with launchd/at to fire a wake trigger without jazz daemon running. See Wake Triggers.

jazz peers

Other people’s agents this machine talks to, and what has been said to or by them.

Peers can be added by invite — jazz peers invite create/accept — or by editing ~/.jazz/config.json directly. See Setting up peers for both paths.

jazz peers invite

jazz persona

install prints the full system prompt and asks before writing it — a persona becomes an agent’s instructions, so non-interactive runs must pass --yes. The catalog is cached under <jazz home>/cache/persona-registry.json and keeps working offline; JAZZ_PERSONA_REGISTRY_URL points Jazz at a self-hosted catalog.

See Personas.

jazz config

See Configuration.

jazz update

In-chat commands

Available inside an interactive session. Type /help for the current list.

Keys: double-Escape interrupts generation or a running tool. Shift+Tab cycles the approval policy. Shift+Enter inserts a newline in the composer; Enter sends.

Shell escapes

In the interactive terminal, type ! <command> when the agent asks you to run a command yourself. Jazz executes the command in the current session directory and sends its bounded stdout, stderr, and exit code to the agent as context for the next response:

> ! ssh user@test rm -r folder
> Did that remove the folder successfully?

The command is executed because you entered it explicitly; it does not wait for the model to call execute_command. The built-in shell denylist, sanitized environment, timeout, process interruption, and 256 KiB per-stream output cap still apply. Output is treated as command data, not as instructions. A non-zero exit code is still passed to the agent so it can explain or suggest the next step. ! is an interactive terminal feature and is not interpreted by jazz run, scheduled jobs, CI, or chat bridges.

Output modes

--output controls formatting; it does not change what goes to stdout vs stderr.

Related

• Surfaces → Headless — the jazz run contract in depth
• Configuration — config file and environment variables
• Tools — every tool and its risk tier
• Workflow frontmatter — the WORKFLOW.md fields