# CLI reference Look up shell commands, their flags, and commands available inside chat. ## Find a command | Task | Commands | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Start work | [`jazz`](#jazz), [`jazz run`](#jazz-run-headless-one-shot), [`jazz agent`](#jazz-agent) | | Save or schedule jobs | [`jazz workflow`](#jazz-workflow), [`jazz goal`](#jazz-goal), [`jazz loop`](#jazz-loop) | | Check work and spend | [`jazz runs`](#jazz-runs), [`jazz spend`](#jazz-spend), [reminders, triggers, jobs](#jazz-reminders-jazz-triggers-jazz-jobs) | | Connect services | [`jazz mcp`](#jazz-mcp), [`jazz peers`](#jazz-peers), [`jazz secrets`](#jazz-secrets), [`jazz webhook`](#jazz-webhook) | | Run elsewhere | [`jazz daemon`](#jazz-daemon), [`jazz hosts`](#jazz-hosts), [`jazz detach`](#jazz-detach), [`jazz imessage`](#jazz-imessage), [`jazz whatsapp`](#jazz-whatsapp) | | Configure and extend | [`jazz config`](#jazz-config), [`jazz persona`](#jazz-persona), [`jazz skill`](#jazz-skill), [`jazz plugin`](#jazz-plugin), [`jazz memory`](#jazz-memory) | | Use your computer (experimental) | [`jazz computer`](#jazz-computer) | | Update | [`jazz update`](#jazz-update) | | Work inside chat | [Slash commands](#in-chat-commands), [keyboard shortcuts](#keyboard-shortcuts), [file mentions](#mentioning-files-with-) | ## Help ```bash jazz --help jazz help jazz help run jazz run --help jazz workflow --help jazz workflow run --help ``` `jazz --help` and `jazz help` show global options and top-level commands. `jazz help run` and `jazz run --help` show run arguments and flags. For a nested command, use its full path followed by `--help`. Inside chat, `/help` lists chat commands and `/help loop` shows the forms of one command. ## Global options Available on every command. | Flag | Effect | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-v, --verbose` | Verbose logging | | `--debug` | Debug-level logging | | `--config ` | Use a specific config file (also `JAZZ_CONFIG_PATH`). A path that does not exist, or a file that is not valid, stops the command with the reason and exit code `1` | | `--data-dir ` | Directory holding this invocation's config, data, and keyring entries (overrides `$JAZZ_HOME`; defaults to `~/.jazz`). Lets one host run several independent agents by flag | | `--no-tui` | Disable the full-screen interface; use plain terminal output for CI, scripts, or small terminals. Same as `JAZZ_NO_TUI=1` | | `--output ` | `rendered` \| `hybrid` (default) \| `raw` (no formatting) \| `quiet` (suppress output). Same as `JAZZ_OUTPUT_MODE` | | `--dangerously-allow-reading-secrets` | Let agents load [saved secrets](#jazz-secrets) and use typed ones without a person approving each use, under every approval mode. For unattended runs that have nobody to ask. Same as `JAZZ_DANGEROUSLY_ALLOW_READING_SECRETS=1` | | `--version` | Print the version | | `-h, --help` | Print help | --- ## `jazz` With no arguments, opens the home screen. Choose an agent and type a message to start work. Use `/new` to start a fresh conversation, `/create` to create an agent, `/agents` to manage agents, `/resume` to continue a conversation, and `/settings` to configure providers, display, and limits. The slash menu ranks command-name prefixes first, then substring matches. On home, `/re` offers `/resume` before `/create`; Enter runs the highlighted command. Global options work here too: `jazz --debug` and `jazz --data-dir ~/work` open the same home. The home needs a terminal. Without one (stdin or stdout piped, cron, CI), or with `--no-tui`, it prints what to run instead and exits `2` without touching your configuration. On a terminal that is too limited for the full-screen interface (`TERM=dumb`, `CI` set, a screen reader via `JAZZ_A11Y=1` or `INK_SCREEN_READER=1`, or a window under 32 columns by 10 rows), Jazz uses the classic inline interface, which prompts the same way. --- ## `jazz run`: headless, one-shot Runs one agent turn from a prompt. The answer goes to stdout; status messages and progress go to stderr. ```bash jazz run --agent [prompt] ``` The prompt comes from the positional argument, from an `--input-stdin` frame, or from piped stdin when neither is given and stdin is not a TTY. Only a positional or framed prompt may back a memory write; plain piped stdin is treated as untrusted text. With `--input-stdin`, send the prompt as JSON on the first line. Subsequent lines are available for interactive replies. | Flag | Default | Purpose | | ------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--agent ` | **required** | Agent id or name | | `--json` | off | Emit one JSON envelope: `{ ok, answer, costUSD, tokenUsage, toolCalls }` | | `--conversation ` | none | Stable conversation key. Loads prior history before the run, saves the transcript after, which gives stateless bridges per-chat memory | | `--approval-policy

` | none | `read-only` \| `low-risk` \| `high-risk`. Tools above the tier are **declined** | | `--auto-approve-tools ` | none | Comma-separated tool names allowed regardless of policy; narrower than raising the whole tier | | `--propose-goals` | off | Let the agent propose a goal for work that outlasts the run; the proposal waits for `jazz goal accept` | | `--timezone ` | UTC | Time zone used to resolve reminder times, such as `Europe/Paris` | | `--watch ` | none | Watch the run: NDJSON progress on stderr: `tools`, `reasoning`, `text`, `usage`, `approval`, `subagent`, `spend`, `all` (comma-separated). Alias of `--events`; pass one or the other, not both | | `--reasoning ` | agent config | `minimal` \| `low` \| `medium` \| `high` \| `xhigh` \| `max` \| `disable`; a level the model does not accept runs at the nearest one it does, with a warning on stderr | | `--timeout ` | none | Hard deadline for the whole run. Work stops at 85% of it and the agent answers in the rest; a run still going at the deadline is killed as a failure. **No default**: unset, a run goes on until it finishes or a budget trips | | `--max-iterations ` | unattended: 100 | Cap reasoning iterations. `0` = unlimited. Unlimited by default in a terminal (type `continue` after any stop); `100` when unattended. User-visible warning at 50/70/90% of the cap | | `--max-subagent-iterations ` | unattended: 30 | Cap iterations for sub-agent runs started by this run. `0` = unlimited. Unlimited by default in a terminal; `30` when unattended | | `--max-cost-usd <$>` | none | Abort once cumulative spend (own + sub-agent) reaches this many dollars, checked between iterations | | `--max-tokens ` | none | Abort once cumulative prompt + completion tokens (own run only, not sub-agents) reach this count, checked between iterations: needs no model pricing | | `--max-duration-ms ` | none | Wall-clock budget. Work stops at 85% of it, interrupting a model call or tool in flight, and the agent answers in the rest. Agent pressure nudges at 50/80/90% | | `--stream` | auto | Force streaming. Text and reasoning event categories enable it automatically unless `--no-stream` is set | | `--no-stream` | off | Disable streaming | | `--interactive-stdin` | off | Let a bridge relay questions and approvals as stdin/stdout events | | `--ephemeral` | off | Do not load or save Jazz conversation/session history; withhold long-term memory writes | | `--input-stdin` | off | Read `{"prompt": ..., "history": [...]}` from the first stdin line, keeping a relayed message off argv. `history` needs `--ephemeral` | | `--park` | off | Persist the run and exit `2` at an unanswered approval; resume it with `jazz runs approve` | | `--with-vision

` | agent config | Bind an image-analysis companion for this run | | `--with-audio

` | agent config | Bind an audio-analysis companion for this run | | `--with-video

` | agent config | Bind a video-analysis companion for this run | `--max-cost-usd` and `--max-tokens` are soft checkpoints, checked between iterations. `--max-duration-ms` is a deadline: it interrupts the run wherever it is and still returns a result. Whatever stops a run, the agent gets one last request without tools to answer from what it gathered. See [Configuration → run budgets](./configure/jazz.md#run-budgets) for the enforcement model and how they differ from `--timeout`. **Exit codes:** `0` on success; `1` on failure, including a run that finishes without a usable answer (an empty zero-token completion, a non-`stop` finish with no text, or a content-filtered answer); `2` when `--park` parks the run on an approval; `130` or `143` when SIGINT or SIGTERM stops it. In plain mode stdout is empty on failure and the message goes to stderr; in `--json` mode stdout always carries exactly one object, with a `code` on failures (`failed`, `empty_response`, `no_answer`, `content_filtered`, `interrupted`). A cut-off answer (`truncated`), an iteration limit (`iterationLimited`) and dropped tools (`toolsDisabled`) are flagged in the envelope and warned about on stderr. See [Headless → JSON](./surfaces/headless.md#json---json). Full contract, examples, and a complete bridge implementation: [Surfaces → Headless](./surfaces/headless.md). --- ## `jazz agent` | Command | Purpose | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `jazz agent list` | List all agents; `--can image\|audio\|video` filters to the ones that can generate that medium. `--json` prints one document. Agent files that cannot be read, or name an unknown provider or reasoning level, are reported on stderr (under `problems` in JSON) | | `jazz agent create` | Create an agent (interactive) | | `jazz agent show ` | Show an agent's details | | `jazz agent edit ` | Edit an agent | | `jazz agent delete ` | Delete an agent. `-y, --yes` / `-f, --force` to skip confirmation | | `jazz agent chat ` | Interactive session with a specific agent, by id or name. `--continue` picks up the agent's most recent saved conversation; add `--conversation ` for a specific one | `agent chat` accepts `--stream` / `--no-stream`, `--max-iterations `, `--max-subagent-iterations `, and `--ephemeral`. Without a terminal, `agent chat` reads messages from stdin, one per line, and ends when stdin does: ```bash echo "What is on my calendar today?" | jazz agent chat assistant ``` Slash commands work the same way (`/exit` ends early). Tool calls that need approval are declined, since nobody can answer the prompt. If stdin ends before any message arrives, `agent chat` says so and exits `2`. For one scripted turn with a parseable result, use [`jazz run`](#jazz-run-headless-one-shot). `agent create` and `agent edit` need a terminal. Without one they exit `2` and point at the agent's JSON file under `$JAZZ_HOME/agents/`, which you can write by hand (see [Configure → Agents](./configure/agents.md)). `persona create`, `persona edit`, and `workflow create` behave the same way. --- ## `jazz workflow` | Command | Purpose | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `jazz workflow create` | Create a new workflow interactively | | `jazz workflow list` | List available workflows (global and local); `--json` prints one document | | `jazz workflow show ` | Show a workflow's prompt and metadata | | `jazz workflow run ` | Run once. See flags below | | `jazz workflow schedule ` | Install a schedule: the workflow's own frequency, or `--cron ""` for another. `--as

` | Interface to bind. Default `127.0.0.1`. Anything else requires a daemon token | | `--serve-peers ` | Also answer questions from configured peers, using this agent. Off unless given | | `--foreground` | Stay attached instead of spawning a background daemon | A bearer token authenticates every route except `/health` on every bind, including loopback. On first start Jazz generates one, stores it in the OS keyring or its protected local fallback, and prints it once. A non-loopback daemon refuses to start if no token can be supplied or stored. When keyring storage is deliberately disabled, loopback alone may warn and continue without one. `/peer/ask` uses separate per-peer credentials; see [`jazz peers`](#jazz-peers). A request that grants authority (accepting or resuming a goal, starting or resuming a loop, approving or answering a parked run, and any write to an agent or persona) also needs the operator token in `X-Jazz-Operator-Token`. It lives only in the OS keyring, so an agent that read the daemon token from disk cannot use it to grant itself more. Without one the daemon grants nothing over HTTP, and the CLI on the machine decides instead. See [Daemon](./concepts/daemon.md#granting-authority-over-http). | Command | Purpose | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `jazz daemon set-token` | Generate (or store `$JAZZ_DAEMON_TOKEN` if set) a token before the daemon's first run: useful when a client needs the value in advance | | `jazz daemon forget-token` | Remove the stored token | | `jazz daemon operator-token` | Generate the operator token that HTTP grants need (accept a goal, start or resume a loop, approve or answer a run), store it in the OS keyring only, and print it once. Refused inside a process a Jazz agent started | | `jazz daemon forget-operator-token` | Remove the operator token, so the daemon grants nothing over HTTP | | `jazz daemon stop` | Stop the background daemon listening on this port | | `jazz daemon status` | Whether this home’s daemon is running and supervised, its last tick and pending work, pause state, today’s spend against the daily caps, and everything waiting for you. `--json`; exits 1 when not running | | `jazz daemon logs` | Print recent daemon output; `-n, --lines ` and `-f, --follow` | | `jazz daemon pause` | Stop background work from starting: goal cycles, loop runs, triggers, and new HTTP runs. Running work finishes and waiting items can still be answered | | `jazz daemon resume` | Start background work again; when a machine daily cap is reached, lift it for the rest of the day. Refused inside a process a Jazz agent started, and over HTTP it needs the operator token | | `jazz daemon install` | Install this as a persistent system service (systemd/launchd). Needs root; generates and stores its own token if none is set (no keyring or `$JAZZ_DAEMON_TOKEN` needed); doesn't report success until `/health` answers; `--serve-peers ` (optional: also answer peers), `--host`, `--port`, `--yes` | | `jazz daemon uninstall` | Remove the service installed by `install`. Needs root; `--yes` | 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](./guides/connect-peers.md) for a full walkthrough, and [Agent-to-agent](./concepts/agent-to-agent.md) for the tier model this exists to serve. A background daemon writes its output to `$JAZZ_HOME/logs/daemon.log`. Without an installed service, nothing restarts it after a reboot; `jazz goal` and `jazz loop` say so when they hand it work. See [Running it persistently](./concepts/daemon.md#running-it-persistently). `jazz wake-trigger fire --agent --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](./tools/index.md#wake-triggers). `jazz reminder fire` and `jazz job run` are the same kind of plumbing for reminders and job batches. --- ## `jazz reminders`, `jazz triggers`, `jazz jobs` What agents have scheduled to happen later, across every agent unless `--agent ` narrows it. | Command | Purpose | | ---------------------------- | ------------------------------------------------------------------------------------------ | | `jazz reminders list` | Reminders set with `remind_me`, soonest first. `--agent`, `--json` | | `jazz reminders cancel ` | Cancel one, and its host scheduler job. `--agent` | | `jazz triggers list` | Wake triggers that will resume a conversation, soonest first. `--agent`, `--json` | | `jazz triggers cancel ` | Cancel one, and its host scheduler job. `--agent` | | `jazz jobs list` | Background job batches still active, with each batch's jobs by status. `--agent`, `--json` | | `jazz jobs cancel ` | Cancel a batch's jobs that have not started; running jobs finish. `--agent` | `--json` prints one envelope: `{"ok":true,"reminders":[…]}`, `{"ok":true,"triggers":[…]}`, or `{"ok":true,"batches":[…]}`. --- ## `jazz goal` Goals are objectives Jazz keeps working toward across runs until verified evidence shows they are done. Each goal has a short name, like `detach-to-prod`, that every command accepts in place of its id. In chat, a goal you accept runs in the chat, asking its approvals there; see [Goals in chat](#goals-in-chat). From a shell, the daemon does the work: accepting or starting a goal launches `jazz daemon` in the background when none is serving this Jazz home. ```bash jazz goal draft --agent assistant "Get every recipe into the new format until ./check.sh passes" jazz goal start --agent assistant --yes --max-cycles 20 "…" jazz goal list jazz goal show jazz goal accept --approval-policy low-risk # start a proposed goal; work begins now jazz goal decline jazz goal approve # allow the step it waits on jazz goal reject [why] # refuse that step; the reason goes to the agent jazz goal answer # answer its question jazz goal pause jazz goal resume [note] # the note steers the next cycle jazz goal cancel ``` `--approval-policy` on `accept` and `start` is what the goal may run while you are away without asking: `read-only`, `low-risk`, or `high-risk` (everything). Above it, a cycle waits for your approval. Without the flag nothing runs unasked, so every gated call waits for you. `approve`, `reject`, and `answer` run the rest of that cycle in the shell; the daemon carries on after. A Jazz agent cannot approve or answer a parked run itself. `draft` prints the plan, or the questions it needs answered first, without creating anything. `start` drafts and, with `--yes`, starts the plan; without `--yes` it only shows it. `--max-cycles` caps the cycles (no limit by default). Each cycle is an ordinary run, held to the agent loop's own limits (`maxIterations`, `maxTokens`, `maxCostUSD`, `maxDurationMs` in config); the goal adds no spend cap of its own. A read-only pass over the current directory informs the plan, as it would in chat; `--no-inspect` drafts from the request alone. With `--json` each command prints one JSON envelope. Exit codes: `0` done, `1` refused or failed, `2` the request needs answers before a plan. ### Goals in chat `/goal ` starts working toward the objective right away, in the same conversation. Nothing is drafted or confirmed first, and the turns look like any other: the same streaming, approvals under the chat's safe or yolo mode, and questions asked inline. When a turn ends, the next one starts on its own, with a `↻ Goal · turn n` line, until the agent reports the goal done. A done report is accepted only when it quotes the tool output that shows the objective holds; otherwise the goal goes on with the reason. If it stops for you (a question, a blocker), the chat asks right there and carries on with your answer. Esc pauses the goal. Anything you type meanwhile goes first and the goal picks up after it. `/goal` shows where it stands, `/goal pause`, `/goal resume [note]`, and `/goal clear` control it, and `/goal help` lists the rest, including `approve`, `reject`, and `answer` for a goal left waiting in the background. A conversation has one goal at a time; setting another offers to drop the current one. Leaving a chat with a goal unfinished asks whether Jazz should finish it in the background, and what it may do there without asking: reading only, low-risk changes, or everything. It carries on in the same conversation, and anything above that authority waits for you. The next `jazz` then lists the conversation first under **Resume conversation (N waiting for you)**, marked with what it waits on. In that picker, choose **End · _goal name_** to stop a waiting goal and keep the conversation history; choose the conversation itself to resume it. Reopening keeps the conversation's original identity, so its goal controls remain available in chat. ## `jazz loop` A loop reruns a prompt for an agent on a schedule, on one conversation of its own, until it ends: "every 10 minutes, check whether the deploy finished and tell me". Each loop has a short name, taken from `--name` or the start of its prompt, that every command accepts in place of its id. Loops run in the daemon, never in the terminal that started them: starting or resuming one launches `jazz daemon` in the background when none is serving this Jazz home. ```bash jazz loop start --agent assistant --every 10m "Check whether the deploy finished and tell me" jazz loop start --agent assistant --every "0 9 * * mon-fri" --until 2026-10-31 --name standup "Summarize yesterday's PRs" jazz loop list jazz loop show jazz loop approve # allow the step its run waits on jazz loop reject [why] # refuse that step; the reason goes to the agent jazz loop answer # answer its run's question jazz loop pause jazz loop resume # a budget-limited loop gets one more default budget jazz loop cancel ``` `--every` takes a duration (`10m`, `1h`, `1h30m`, at least a minute) or a five- or six-field cron expression. Six fields add seconds first: `--every '*/10 * * * * *'` schedules every ten seconds. Cron is read in `--tz` (default: this machine's timezone). An interval loop runs right away; a cron loop waits for its first scheduled time. Runs missed while the daemon was down collapse into one, and a loop never overlaps itself, including while a run waits for an approval. Intervals are measured from the previous run's completion. Actual starts depend on the daemon's polling. A loop ends when its run calls `end_loop` (it gets that tool, and only loop runs do), when it reaches `--max-runs` or `--until`, or when you cancel it. Three failed runs in a row stop it for you to look at; `resume` starts it again. Budget flags cover all runs together: `--max-tokens`, `--max-minutes`, and `--max-cost-usd` (enforced when pricing is known), and each run is held to the agent loop's own limits like any run. A loop that hits one of its budgets is budget-limited until you resume it. `--approval-policy` is what its runs may do without asking: `read-only`, `low-risk`, or `high-risk` (everything). Above it, the run waits; `approve`, `reject`, and `answer` finish that run in the shell, under what the loop's budget has left. Pausing or canceling a loop whose run is waiting drops that run. A Jazz agent cannot start, resume, approve, or answer a loop. With `--json` each command prints one JSON envelope. Exit codes: `0` done, `1` refused or failed. ### Loops in chat `/loop 10m ` (or `/loop every 10m `, or `/loop cron 0 9 * * mon-fri `) starts a loop for the chat's agent in its current directory, after asking what its runs may do without asking. `/loop help` lists the commands; they mirror `jazz loop`. Opening a conversation shows its loops that wait for you, and the next `jazz` counts them under **Resume conversation**. `10m` means every ten minutes; `1h` means every hour. `/loop 10s` is refused: chat intervals must be at least one minute, and chat cron takes exactly five fields. See the [full loop syntax](./concepts/goals-and-loops.md#interval-syntax) for interval units, cron fields, examples, and every chat control. ## `jazz imessage` Reach the agent from Messages. The bare command uses a hosted Photon line and can run on any supported host. `--local` instead uses the Apple account signed into a Mac (macOS 14+) and walks through installing [`imsg`](https://github.com/openclaw/imsg), granting Full Disk Access, and optionally installing a background service. | Command | Purpose | | ---------------------- | --------------------------------------------------------------------------------------------------------- | | `jazz imessage` | Start the bridge. `--local` uses your Mac account; `--agent ` seeds it from an existing agent | | `jazz imessage status` | Whether the local-Mac background service is installed and loaded | | `jazz imessage logs` | Follow the local-Mac service log at `~/.jazz-imessage/bridge.log` by default | | `jazz imessage stop` | Stop the local-Mac launchd service; its plist remains | Who it answers is `IMESSAGE_ALLOWED_HANDLES`, deny-by-default; with nothing set, an interactive first run answers only you, via a `jazz` prefix in a chat with yourself. The background service's environment is snapshotted into its plist at install time: see [Reaching your agent from a chat app](./guides/deploy-a-chat-agent.md#imessage-through-your-own-mac) for changing it afterwards, and [`packages/imessage-bot/README.md`](../packages/imessage-bot/README.md) for every variable. --- ## `jazz whatsapp` Reach the agent from WhatsApp. The bridge links to your account as a device, the way WhatsApp Web does, and runs in the foreground: there is no service installer. | Command | Purpose | | --------------- | ---------------------------------------------------------------------------------------------- | | `jazz whatsapp` | Start the bridge. `--agent ` seeds it from an agent you have, copied into its home | The first run asks whose messages to answer and remembers it in `wa-allowed.json`; `WHATSAPP_ALLOWED_NUMBERS` skips the question and is required where there is no terminal to ask. Pairing is a QR code, or an 8-character code with `WHATSAPP_PAIR_NUMBER` on a headless machine, and happens once: credentials live in `WHATSAPP_AUTH_DIR`. See [Reaching your agent from a chat app](./guides/deploy-a-chat-agent.md#whatsapp) for the walkthrough and [`packages/whatsapp-bot/README.md`](../packages/whatsapp-bot/README.md) for every variable. --- ## `jazz secrets` Secrets saved for every agent on this Jazz home. Values live in the OS keyring (or `$JAZZ_HOME/secrets.json` where there is none); names and descriptions live in `$JAZZ_HOME/saved-secrets.json`. Agents see the names with `list_saved_secrets` and load one into a run with `use_saved_secret`, which you approve every time unless the run was started with `--dangerously-allow-reading-secrets`. Every secret an agent asks for with `ask_user_secret` is saved here too, under the name the agent gives it. See [Secrets the person types](./security/secrets-and-egress.md#secrets-the-person-types). | Command | Purpose | | ------------------------- | --------------------------------------------------------------------- | | `jazz secrets list` | Saved secrets by name and description, never by value. `--json` | | `jazz secrets set ` | Save a secret, typed hidden or piped on stdin. `--description ` | | `jazz secrets rm ` | Forget a saved secret | ## `jazz peers` Other people's agents this machine talks to, and what has been said to or by them. | Command | Purpose | | -------------------------------- | ---------------------------------------------------------------------------------------------------- | | `jazz peers list` | List configured peers and what each may learn. `--json` | | `jazz peers set-token ` | Store a peer's token, read from `$JAZZ_PEER_TOKEN` (or `--from-env `) | | `jazz peers forget-token ` | Remove a peer's stored token | | `jazz peers log` | Everything said to and by a peer, newest first. `--peer `, `--limit `, `--json`, `--follow` | Peers can be added by [invite](./guides/connect-peers.md): `jazz peers invite create/accept` , or by editing `~/.jazz/config.json` directly. See [Setting up peers](./guides/connect-peers.md) for both paths. ### `jazz peers invite` | Command | Purpose | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `jazz peers invite create ` | Create a one-time invite link granting `` a tier once accepted. `--disclosure ` (default `internal`), `--persona ` (which persona answers them), `--expires `, `--host`/`--port` or `--public-url` (reverse-proxy setups), `--as `, `--qr`, `--json`. Defaults: detected public IPv4, port `4747`, disclosure `internal`, expiry `3h`. Use `--host 127.0.0.1` for a same-machine demo. | | `jazz peers invite accept ` | Accept an invite link. `--as `, `--yes` (skip confirmation), `--json`. Stores the peer token and adds `ask_peer` to existing saved tool lists. Partial agent setup exits 1; `--json` includes `backfilled` and `backfillErrors`. | | `jazz peers invite list` | Invites created on this machine. `--json` | | `jazz peers invite revoke ` | Invalidate an invite before it's redeemed | --- ## `jazz persona` | Command | Purpose | | ---------------------------------- | ---------------------------------------------------------------------------------------------------- | | `jazz persona list` | List personas (built-in + custom); `--json` prints one document | | `jazz persona create` | Create a custom persona (interactive) | | `jazz persona show ` | Show a persona by name or id | | `jazz persona edit ` | Edit a custom persona | | `jazz persona delete ` | Delete a custom persona | | `jazz persona browse` | Browse the library and install a persona (interactive). `--refresh` | | `jazz persona search` | List every persona the library offers. `--refresh` | | `jazz persona add ` | Install a library persona. `--as ` (local name), `-y`/`--yes` (skip confirmation), `--refresh` | `add` 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 `/cache/persona-registry.json` and keeps working offline; `JAZZ_LIBRARY_URL` points Jazz at a self-hosted library. See [Personas](./concepts/personas.md). --- ## `jazz skill` | Command | Purpose | | --------------------------- | ------------------------------------------------------------------------------------------------------- | | `jazz skill list` | List the skills agents can load, by source; `--json` prints one document | | `jazz skill browse` | Browse the reviewed skill marketplace and install a skill (interactive). `--refresh` | | `jazz skill search [query]` | Search marketplace skill names, descriptions, tags, and metadata. `--refresh` | | `jazz skill add ` | Install one reviewed `SKILL.md` into `~/.jazz/skills/`. `-y`/`--yes` (skip confirmation), `--refresh` | | `jazz skill remove ` | Remove a global skill and its files. `-y`/`--yes` skips confirmation and is required non-interactively. | Marketplace skills are instruction-only. Installation prints the complete file, asks for confirmation, writes only `SKILL.md`, and never executes or imports the downloaded text. Non- interactive installs must pass `--yes`. The catalog is cached under `/cache/skill-registry.json`, works offline after a successful fetch, and uses `JAZZ_LIBRARY_URL` when you host a compatible library yourself. Skills can influence an agent's behavior but grant no tools, credentials, network access, or approval authority. Read the source for prompt injection or unsafe guidance before installing. See [Skills](./concepts/skills.md). --- ## `jazz plugin` Every command below that takes `` also accepts the `owner/repo` (or GitHub URL) you installed from — it resolves to the installed plugin. Trust and enable prompt for a plain yes/no confirmation. | Command | Purpose | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `jazz plugin init ` | Scaffold a types-only SDK plugin project. `--id`, `--name` | | `jazz plugin dev [directory]` | Pack and audit in a disposable host. `--hook route.skills --input ` | | `jazz plugin pack [directory]` | Emit `plugin.mjs`, its SHA-256, and `catalog-entry.json` | | `jazz plugin add ` | Install from a GitHub `owner/repo` (default, `@ref` to pin), a local source dir, a manifest, or a catalog id; does not trust or enable | | `jazz plugin inspect ` | Show exact digest, declarations, grants, enablement, and secret status. `--json` | | `jazz plugin trust ` | Acknowledge full OS-user code execution for the current digest; `--yes` grants it headlessly | | `jazz plugin enable [--agent ]` | Grant current egress consent and enable for one agent, or for all agents when `--agent` is omitted; `--yes` grants it headlessly | | `jazz plugin disable [--agent ]` | Prevent new dispatches for one agent or all agents | | `jazz plugin update [source]` | Re-fetch and install an update, retaining one rollback artifact and disabling pending grants. Omitting `source` re-pulls the recorded source, so `jazz plugin update owner/repo` re-fetches a GitHub source install | | `jazz plugin rollback ` | Swap current/previous artifacts and disable pending grants | | `jazz plugin doctor ` | Check artifact, grants, declarations, and required secrets. `--json` | | `jazz plugin remove ` | Remove state/artifacts and Jazz-owned secrets. `--keep-secrets` | | `jazz plugin list` | List installed plugin state | | `jazz plugin gc` | Remove unreferenced, unloaded artifacts | | `jazz plugin secret set ` | Store a declared plugin-scoped credential | | `jazz plugin secret status ` | Report whether a credential comes from environment, keyring, file, or is missing | | `jazz plugin secret forget ` | Delete a Jazz-owned plugin credential; environment values are unaffected | Without `--yes`, trust and consent require a local interactive terminal, because a headless run cannot show the confirmation prompt; `--yes` is the consent itself and works from a script, a pipe, or CI. This includes explicit consent for a `classify.command-risk` policy hook: it may send bounded command text to its declared destination and its validated verdict can affect whether an eligible `execute_command` call needs approval. Static tool risks, allowlists, approval tiers, and the shell denylist remain enforced by Jazz. See [Plugins](./configure/plugins.md). --- ## `jazz config` | Command | Purpose | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `jazz config show` | Show all configuration values, secrets redacted; `--reveal` prints them | | `jazz config validate` | Check config files without starting the application | | `jazz config get ` | Print one value and nothing else, redacted when it is or holds a secret; `--reveal` prints it. Exits `1` if unset | | `jazz config set [value]` | Set one value | `config validate` also checks every agent file: one that cannot be read, or names a provider or reasoning level Jazz does not know, fails the check with exit code `1`; a tool name no built-in provides is a warning, since an MCP server, plugin, or custom tool may supply it. `config set` refuses a key Jazz does not read, including an API key for a provider that does not exist (`llm.opneai.api_key`), and trims pasted keys. `jazz config set ` with no value prompts for the key, so it never lands in your shell history, and checks it with the provider where there is a free endpoint to ask. See [Configuration](./configure/jazz.md). --- ## `jazz memory` Memory is shared by every agent, so these commands address scopes and paths directly. | Command | Purpose | | ---------------------------- | ----------------------------------------------------------------- | | `jazz memory list [scope]` | List every scope on disk, or every file in one scope | | `jazz memory show ` | Print one memory file as the agents read it | | `jazz memory forget ` | Permanently delete one memory file | | `jazz memory explain ` | Show provenance and recent opportunity receipts for one entry | | `jazz memory recall` | Report memory consultation; `--surface ` filters it | | `jazz memory review` | Keep or drop waiting memory suggestions and lessons, 10 at a time | | `jazz memory accept ` | Save one waiting suggestion or lesson to memory | | `jazz memory reject ` | Drop one waiting suggestion or lesson without saving it | Conversation history and current working state are separate. See [Conversations, working state, and memory](./concepts/conversations-and-memory.md). --- ## `jazz webhook` | Command | Purpose | | ----------------------------------- | ------------------------------------------------------------------------------------ | | `jazz webhook token ` | Generate and store a bearer token; print it once | | `jazz webhook forget-token ` | Remove a webhook's stored token | | `jazz webhook secret ` | Generate and store the secret its sender signs bodies with (GitHub's webhook secret) | | `jazz webhook forget-secret ` | Remove a webhook's stored signing secret | Webhook definitions live in Jazz configuration. See [Webhooks](./concepts/webhooks.md). --- ## `jazz update` | Command | Purpose | | --------------------- | ------------------------------------ | | `jazz update` | Update Jazz to the latest version | | `jazz update --check` | Check for updates without installing | Both exit 1 when the version check or the install fails, so a script can tell a failed update from "already up to date". --- ## Command-specific flags The `jazz run` and `jazz workflow run` flag tables appear above. The following table lists the options for every other public command that accepts them. Commands without their own options still accept [global options](#global-options) and `-h, --help`. | Command | Flag | Effect | | --------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `jazz agent list` | `--can ` | Only agents whose model can generate this: image, audio, or video. Shows how to get one when none can. | | `jazz agent list` | `--json` | Print one JSON document, with unreadable or invalid agent files under problems | | `jazz agent delete` | `-y, --yes` | Delete without asking for confirmation | | `jazz agent delete` | `-f, --force` | Alias for --yes | | `jazz agent chat` | `--stream` | Force streaming mode (real-time output) | | `jazz agent chat` | `--max-iterations ` | Maximum agent reasoning iterations per turn (`0` = unlimited; unlimited in a terminal, 100 unattended; warning at 50/70/90% of the cap) | | `jazz agent chat` | `--max-subagent-iterations ` | Maximum iterations for sub-agent runs (`0` = unlimited; unlimited in a terminal, 30 unattended) | | `jazz agent chat` | `--ephemeral` | Skip Jazz conversation/session persistence: no conversation history save, no session log, and long-term memory writes are withheld. File tools and local telemetry still follow their normal configuration. | | `jazz agent chat` | `--continue` | Continue the agent's most recent saved conversation | | `jazz agent chat` | `--conversation ` | With --continue, the saved conversation to continue | | `jazz persona list` | `--json` | Print one JSON document | | `jazz persona browse` | `--refresh` | Re-fetch the catalog instead of using the cached snapshot | | `jazz persona search` | `--refresh` | Re-fetch the catalog instead of using the cached snapshot | | `jazz persona add` | `--as ` | Install under a different local name | | `jazz persona add` | `-y, --yes` | Skip the confirmation prompt (required when non-interactive) | | `jazz persona add` | `--refresh` | Re-fetch the catalog instead of using the cached snapshot | | `jazz skill list` | `--json` | Print one JSON document | | `jazz skill browse` | `--refresh` | Re-fetch the catalog instead of using the cached snapshot | | `jazz skill search` | `--refresh` | Re-fetch the catalog instead of using the cached snapshot | | `jazz skill add` | `-y, --yes` | Skip the confirmation prompt (required when non-interactive) | | `jazz skill add` | `--refresh` | Re-fetch the catalog instead of using the cached snapshot | | `jazz skill remove` | `-y, --yes` | Skip the confirmation prompt (required when non-interactive) | | `jazz plugin init` | `--id ` | Reverse-DNS plugin id | | `jazz plugin init` | `--name ` | Human-readable plugin name | | `jazz plugin dev` | `--hook ` | Invoke a hook after auditing registrations | | `jazz plugin dev` | `--input ` | JSON input for --hook | | `jazz plugin add` | `--json` | Emit JSON | | `jazz plugin list` | `--json` | Emit JSON | | `jazz plugin inspect` | `--json` | Emit JSON | | `jazz plugin trust` | `-y, --yes` | Grant the consent without a confirmation prompt; also works headlessly (a script, pipe, or CI) | | `jazz plugin enable` | `--agent ` | Agent id or name; omit to enable for all agents | | `jazz plugin enable` | `-y, --yes` | Grant the consent without a confirmation prompt; also works headlessly (a script, pipe, or CI) | | `jazz plugin disable` | `--agent ` | Agent id; omit to disable everywhere | | `jazz plugin remove` | `--keep-secrets` | Keep Jazz-owned plugin secrets | | `jazz plugin doctor` | `--json` | Emit JSON | | `jazz plugin secret status` | `--json` | Emit JSON | | `jazz config get` | `--reveal` | Print secret values in full | | `jazz config show` | `--reveal` | Print secret values in full | | `jazz computer grant` | `--expires ` | How long the grant lasts, such as 8h (default 8h, at most 7d) | | `jazz computer grant` | `--idle ` | End a run's access after this long without an action (default 30m) | | `jazz computer grant` | `--foreground` | Let Jazz bring the app to the front, for apps the background tools cannot drive | | `jazz computer grant` | `--name ` | A display name to show while the app is not running | | `jazz computer log` | `--limit ` | How many entries to show (default 20) | | `jazz hosts add` | `--allow-file-secrets` | Let a server without an OS keyring store handed-off API keys in ~/.jazz/secrets.json | | `jazz detach reclaim` | `--overwrite` | Let remote versions win where a file also changed locally | | `jazz memory recall` | `--surface ` | Only report one surface (cli, telegram, discord) | | `jazz mcp add` | `-f, --file ` | Read MCP server JSON from a file | | `jazz mcp add` | `-t, --transport ` | Transport to use: stdio (default) or http | | `jazz mcp add` | `-e, --env ` | Environment variable for a stdio server | | `jazz mcp add` | `-H, --header ` | HTTP header for an http server | | `jazz mcp add` | `--trusted` | Let this server's read-only annotations skip approval prompts | | `jazz mcp list` | `--tools` | Connect to each server and show the tools it advertises | | `jazz mcp list` | `--json` | Print one JSON document (no env values or headers) | | `jazz mcp remove` | `-y, --yes` | Skip the confirmation prompt | | `jazz update` | `--check` | Check for updates without installing | | `jazz daemon` | `--port ` | Port to listen on | | `jazz daemon` | `--host
` | Interface to bind. Anything other than loopback requires a daemon token (env or keyring). | | `jazz daemon` | `--serve-peers ` | Also answer questions from configured peers, using this agent. Off unless given: a daemon for your own use should not quietly answer strangers. | | `jazz daemon` | `--foreground` | Stay attached to the terminal (default is background). Required for systemd/launchd. | | `jazz daemon pause` | `--json` | Emit a single JSON envelope | | `jazz daemon resume` | `--json` | Emit a single JSON envelope | | `jazz daemon status` | `--json` | Emit a single JSON envelope | | `jazz daemon logs` | `-f, --follow` | Keep printing new output until interrupted | | `jazz daemon logs` | `-n, --lines ` | How many recent lines to print | | `jazz daemon install` | `--yes` | Skip the confirmation prompt | | `jazz daemon uninstall` | `--yes` | Skip the confirmation prompt | | `jazz goal draft` | `--agent ` | Agent ID or name that will work on the goal | | `jazz goal draft` | `--no-inspect` | Draft without first reading the current directory (by default a read-only pass informs the plan) | | `jazz goal draft` | `--json` | Emit a single JSON envelope | | `jazz goal start` | `--agent ` | Agent ID or name that will work on the goal | | `jazz goal start` | `--no-inspect` | Draft without first reading the current directory (by default a read-only pass informs the plan) | | `jazz goal start` | `--yes` | Accept the drafted plan without showing it for review first | | `jazz goal start` | `--json` | Emit a single JSON envelope | | `jazz goal start` | `--approval-policy ` | What the goal may run without asking once accepted: read-only \| low-risk \| high-risk (high-risk runs everything). Above it, a cycle waits for approval. | | `jazz goal start` | `--max-cycles ` | Most cycles the goal may run (default: no limit; each cycle is held to the agent loop's own limits) | | `jazz goal list` | `--json` | Emit a single JSON envelope | | `jazz goal show` | `--json` | Emit a single JSON envelope | | `jazz goal accept` | `--json` | Emit a single JSON envelope | | `jazz goal accept` | `--approval-policy ` | What the goal may run without asking: read-only \| low-risk \| high-risk (high-risk runs everything). Above it, a cycle waits for approval. | | `jazz goal decline` | `--json` | Emit a single JSON envelope | | `jazz goal approve` | `--json` | Emit a single JSON envelope | | `jazz goal reject` | `--json` | Emit a single JSON envelope | | `jazz goal answer` | `--json` | Emit a single JSON envelope | | `jazz goal pause` | `--json` | Emit a single JSON envelope | | `jazz goal resume` | `--json` | Emit a single JSON envelope | | `jazz goal cancel` | `--json` | Emit a single JSON envelope | | `jazz loop start` | `--agent ` | Agent ID or name that runs the prompt | | `jazz loop start` | `--every ` | How often: a duration like 10m or 1h30m (at least 1m), or a cron expression like `0 9 * * mon-fri` | | `jazz loop start` | `--name ` | What to call the loop (default: the start of its prompt) | | `jazz loop start` | `--tz ` | IANA timezone a cron schedule and --until are read in (default: this machine's) | | `jazz loop start` | `--until ` | When the loop ends on its own: a duration like 8h, a clock time like 18:00, or 2026-10-01 09:00 | | `jazz loop start` | `--approval-policy ` | What a run may do without asking: read-only \| low-risk \| high-risk (high-risk runs everything). Above it, the run waits for approval. | | `jazz loop start` | `--max-runs ` | Most runs before the loop completes | | `jazz loop start` | `--max-tokens ` | Token budget across all runs | | `jazz loop start` | `--max-minutes ` | Active-time budget across all runs, in minutes | | `jazz loop start` | `--max-cost-usd ` | Dollar budget across all runs (enforced when pricing is known) | | `jazz loop start` | `--json` | Emit a single JSON envelope | | `jazz loop list` | `--json` | Emit a single JSON envelope | | `jazz loop show` | `--json` | Emit a single JSON envelope | | `jazz loop approve` | `--json` | Emit a single JSON envelope | | `jazz loop reject` | `--json` | Emit a single JSON envelope | | `jazz loop answer` | `--json` | Emit a single JSON envelope | | `jazz loop pause` | `--json` | Emit a single JSON envelope | | `jazz loop resume` | `--json` | Emit a single JSON envelope | | `jazz loop cancel` | `--json` | Emit a single JSON envelope | | `jazz imessage` | `--agent ` | Seed the bridge from one of your agents, copied into its own home | | `jazz imessage` | `--local` | Use your own Mac and Apple account instead of a hosted line. Messages avoid Photon, but model and tool traffic still follow the agent configuration; the agent answers as you and needs a trigger word | | `jazz whatsapp` | `--agent ` | Seed the bridge from one of your agents, copied into its own home | | `jazz reminders list` | `--agent ` | Only this agent's | | `jazz reminders list` | `--json` | Emit a single JSON envelope | | `jazz reminders cancel` | `--agent ` | Only look in this agent's | | `jazz triggers list` | `--agent ` | Only this agent's | | `jazz triggers list` | `--json` | Emit a single JSON envelope | | `jazz triggers cancel` | `--agent ` | Only look in this agent's | | `jazz jobs list` | `--agent ` | Only this agent's | | `jazz jobs list` | `--json` | Emit a single JSON envelope | | `jazz jobs cancel` | `--agent ` | Only look in this agent's | | `jazz secrets list` | `--json` | Emit a single JSON envelope { ok, secrets } | | `jazz secrets set` | `--description ` | What the secret is for, shown to agents | | `jazz peers list` | `--json` | Emit a single JSON envelope { ok, peers } | | `jazz peers set-token` | `--from-env ` | Environment variable holding the token | | `jazz peers log` | `--peer ` | Only entries for this peer | | `jazz peers log` | `--limit ` | How many entries to show | | `jazz peers log` | `--json` | Emit a single JSON envelope { ok, entries } | | `jazz peers log` | `-f, --follow` | Keep watching and print new entries as they land | | `jazz peers invite create` | `--disclosure ` | What the invitee may learn once they accept: none, public, internal, private (default internal) | | `jazz peers invite create` | `--expires ` | How long the link stays redeemable, e.g. 30m, 24h, 7d (default 3h) | | `jazz peers invite create` | `--host
` | Address the invitee can reach; defaults to automatic public-IP detection | | `jazz peers invite create` | `--port ` | Port your daemon answers on (default 4747) | | `jazz peers invite create` | `--as ` | What to call yourself to the invitee. Defaults to this machine's hostname. | | `jazz peers invite create` | `--persona ` | Which persona answers this invitee once accepted. Defaults to your daemon's --serve-peers agent as-is. | | `jazz peers invite create` | `--public-url ` | Overrides --host/--port for the printed link, such as `https://bob-agent.example.com`, for a daemon behind a reverse proxy. | | `jazz peers invite create` | `--qr` | Also print the link as a terminal QR code | | `jazz peers invite create` | `--json` | Emit a single JSON envelope { ok, id, url, expiresAt } | | `jazz peers invite accept` | `--as ` | What to call them locally. Defaults to the name they invited you as. | | `jazz peers invite accept` | `--yes` | Skip the confirmation prompt | | `jazz peers invite accept` | `--json` | Emit a single JSON envelope { ok, name, backfilled, backfillErrors } | | `jazz peers invite list` | `--json` | Emit a single JSON envelope { ok, invites } | | `jazz runs list` | `--agent ` | Only runs belonging to this agent | | `jazz runs list` | `--conversation ` | Only runs from this conversation | | `jazz runs list` | `--all` | Include runs that already finished, with what they cost. Records are kept for 7 days. | | `jazz runs list` | `--json` | Emit a single JSON envelope { ok, runs } | | `jazz runs show` | `--json` | Emit a single JSON envelope { ok, run } | | `jazz runs approve` | `--json` | Emit a single JSON envelope { ok, runId, answer } | | `jazz runs answer` | `--response ` | Your answer to the question. An empty string tells the run you declined to answer. | | `jazz runs answer` | `--json` | Emit a single JSON envelope { ok, runId, answer } | | `jazz runs secret` | `--json` | Emit a single JSON envelope { ok, runId, answer } | | `jazz runs reject` | `--note ` | Tell the agent why, so it can try something else | | `jazz runs reject` | `--json` | Emit a single JSON envelope { ok, runId, answer } | | `jazz runs cancel` | `--json` | Emit a single JSON envelope { ok, runId } | | `jazz spend` | `--json` | Emit a single JSON envelope { ok, today, thisMonth, caps } | | `jazz notify list` | `--json` | Emit a single JSON envelope { ok, targets, implicit } | | `jazz notify add` | `--kind ` | desktop, ntfy, webhook, telegram or discord | | `jazz notify add` | `--chat-id ` | Telegram chat id to post in | | `jazz notify add` | `--channel-id ` | Discord channel id, when posting as a bot instead of a webhook | | `jazz notify add` | `--url ` | ntfy topic URL, or the endpoint a webhook target posts JSON to | | `jazz notify add` | `--api-base-url ` | Self-hosted Telegram Bot API or Discord API base URL | | `jazz notify add` | `--events ` | Comma-separated: waiting, paused, reminder, unattended-failed, spend-cap (default: all) | | `jazz notify add` | `--approve-from-chat` | A running Jazz bridge serves this chat, so approval requests offer /approve | | `jazz notify test` | `--json` | Emit a single JSON envelope { ok, target } | | `jazz notify outbox` | `--json` | Emit a single JSON envelope { ok, notifications } | | `jazz notify retry` | `--json` | Emit a single JSON envelope { ok, rearmed, delivered, failed } | | `jazz workflow list` | `--json` | Print one JSON document | | `jazz workflow schedule` | `--cron ` | Cron expression to run on, instead of the workflow's schedule: field | | `jazz workflow schedule` | `--as