# Jazz — full documentation > Jazz is an open-source AI agent harness that runs a general-purpose AI agent on your own machine — > terminal, scripts, cron, CI, Telegram, Discord. Self-hosted and fully local-capable: > 22 LLM providers, including offline models via Ollama and llama.cpp. > MIT licensed. Install with a single curl command; ships as a self-contained binary for macOS and Linux. Install: curl -fsSL https://github.com/lvndry/jazz/releases/latest/download/install.sh | bash Source: https://github.com/lvndry/jazz Table of contents with per-page links: https://lvndry.github.io/jazz/llms.txt --- ## Getting started with Jazz Source: https://lvndry.github.io/jazz/docs/getting-started.md # Getting started with Jazz Use this path if you have not run Jazz before. 1. [Install Jazz and run your first agent](./quick-start.md). 2. [Create an agent for a specific job](./create-an-agent.md). 3. Learn the [CLI](../surfaces/cli.md): resume work, attach files, and control runs. 4. Choose a next step: - build a [CI reviewer using OpenRouter or a self-hosted model](../guides/pr-review.md); - create a reusable [accountability persona named Goggins](../guides/goggins-accountability-agent.md); - combine a cheap text model with [specialist media companions](../guides/media-companions.md); - run locally with [Ollama, llama.cpp, vLLM, or SGLang](./local-models.md); - reach the agent through a [chat surface](../guides/deploy-a-chat-agent.md); - run work [headlessly](../surfaces/headless.md) or [on a schedule](../surfaces/scheduled.md); - create a chart or interactive dashboard with [compositions](../concepts/compositions.md); - keep Jazz working with [goals and loops](../concepts/goals-and-loops.md); - connect [MCP servers](../configure/mcp.md) or a [web-search provider](../configure/web-search.md). To remove Jazz later, [uninstall](./uninstall.md) lists everything it puts on the machine. Jazz uses one agent definition across every surface. You do not need to recreate an agent when you move from the terminal to a script, schedule, webhook, or chat bot. --- ## Creating agents Source: https://lvndry.github.io/jazz/docs/getting-started/create-an-agent.md # Creating agents Create an agent with its own model, persona, tools, and skills. ```bash jazz agent create ``` The wizard asks for a provider, model, reasoning level, persona, name, and tools. For a first agent, choose the `default` persona; for repository work, choose `coder`. After creating it, start a conversation: ```bash jazz agent chat ``` To script agent creation, write the JSON file directly (shape below) or copy an existing one. --- ## What the wizard asks | Choice | Guidance | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Provider + model** | See [Providers](../configure/providers.md). `openrouter` with a free model costs nothing; `ollama` keeps everything local unless you pick a `:cloud` model, which needs an [Ollama API key](../configure/providers.md#ollama) | | **Reasoning** | How much reasoning effort to request from a model that supports it. You can leave the default selected. | | **Persona** | `default`, `coder`, `researcher`, or one of yours. See [Personas](../concepts/personas.md) | | **Name** | How you'll refer to it: `jazz agent chat reviewer`. | | **Toolset** | Extra capabilities to add, including configured MCP servers. Built-in tools are supplied by the persona's tool profile; use `deniedTools` in the agent file for hard per-agent restrictions. Selecting an MCP server may connect to it | --- ## Configure the agent file Agents are one JSON file each under `~/.jazz/agents/.json`: ```json { "id": "1MeNdd1bmkf498bzCoTGKL", "name": "reviewer", "config": { "persona": "coder", "llm": { "provider": "anthropic", "model": "claude-sonnet-4-5", "reasoning": "medium" } } } ``` Useful optional fields: | Field | Effect | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `llm.reasoning` | `disable`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. The selected model validates the control surface. | | `llm.temperature` | Sampling temperature from `0` to `2`. Not asked by the wizard. Unset means Jazz sends nothing and the provider's default applies; models that reject a custom temperature ignore it | | `llm.summarizerModel` | `provider/model` used for context compaction **and** `execute_command` risk classification: point it at something cheap | | `customTools` | Declare extra tools (`record` or `command` handlers) without changing Jazz. See [Agent configuration](../configure/agents.md#custom-tools) | | `companions` | Bind specialist models (a `provider/model` id or a named companion) for image, audio, or video analysis and generation without changing the primary model; see [Model companions](../concepts/media.md) | | `envAllowlist` | Exempt specific env vars from secret scrubbing for `execute_command` | | `deniedTools` | Remove named tools from this agent after every other capability source is applied | `createdAt` and `updatedAt` are optional in a file you write by hand. Jazz stamps them when it creates or saves the agent, and falls back to the file's own created and modified times when they are absent. The `tools` field adds capabilities; it does not restrict built-in tools. Use `deniedTools` for restrictions. See [Agent configuration](../configure/agents.md) for every field, including skill selection and memory scopes. --- ## Copying an agent To start from an existing agent, copy its file: ```bash cp ~/.jazz/agents/.json ~/.jazz/agents/reviewer-strict.json # edit id + name so they don't collide, then adjust ``` The `id` must be unique; `name` is what you type on the command line. --- ## Choosing a model - **For digests and summaries:** try a fast, inexpensive model and check the output against the source material. - **For code changes, reviews, and other multi-step tasks:** choose a model that handles reasoning and tool use reliably. Test it on representative work before scheduling it unattended. - **A self-hosted model (`ollama`, `llamacpp`, `vllm`, `sglang`) when prompts must stay on your infrastructure.** No provider key unless the server requires one, and no provider per-token cost. Network-capable tools and exporters remain separate choices; see [Local and air-gapped models](./local-models.md). - **A cheaper `llm.summarizerModel` for supporting calls.** It handles both compaction and command-risk classification. Check that it can do both reliably. - **Primary model for orchestration, companions for media.** Keep the tool-capable model you trust and route image, audio, or video understanding and generation to specialists. If a task turns out harder than expected, switch to an agent configured with a stronger model using `/switch` (or `/models`). --- ## Next steps - [Personas](../concepts/personas.md): define reusable behavior and voice - [Tools](../concepts/tools.md): what it can do, and what the risk tiers mean - [Workflows](../concepts/workflows.md): run it on a schedule - [Model companions](../concepts/media.md): tune one agent with several specialist models --- ## Run Jazz with local and air-gapped models Source: https://lvndry.github.io/jazz/docs/getting-started/local-models.md # Run Jazz with local and air-gapped models Jazz can run against a self-hosted inference server such as [Ollama](https://ollama.ai/), [llama.cpp](https://github.com/ggml-org/llama.cpp), [vLLM](https://docs.vllm.ai/en/latest/serving/online_serving/openai_compatible_server/), or [SGLang](https://docs.sglang.ai/). Local providers need no API key unless the server requires one. `JAZZ_OFFLINE` disables Jazz's public catalog, library, and update requests; it is a convenience switch, **not a network sandbox**. Use host or container egress controls for an enforced air gap. ## Quick setup (Ollama) 1. Install Ollama on the server and pull a tool-capable model: ```bash ollama pull qwen3 ``` 2. Set the environment for the Jazz process: ```bash export JAZZ_OFFLINE=1 export OLLAMA_BASE_URL=http://127.0.0.1:11434 ``` Point `OLLAMA_BASE_URL` at the machine running Ollama if it lives elsewhere on the internal network. Alternatively use the config file: ```json { "llm": { "ollama": { "base_url": "http://ollama.internal:11434" } } } ``` Or set it interactively: run `jazz`, enter `/settings`, then choose **Model providers**, pick Ollama, llama.cpp, vLLM, or SGLang, and enter the server address as `host:port` (or a full URL). Jazz adds the scheme and the provider's REST path for you, so `192.168.1.50:11434` is enough. This is the same `base_url` as above and takes precedence over the environment variable. 3. Create an agent and chat. Jazz lists models straight from Ollama's `/api/tags` endpoint, so no external catalog is needed: ```bash jazz agent create jazz agent chat ``` llama.cpp works the same way via `LLAMACPP_BASE_URL` (default `http://127.0.0.1:8080/v1`), or the first-use server-URL prompt in `jazz agent create`; start `llama-server` with `--jinja` for tool calling. For vLLM, choose the `vllm` provider. It defaults to `http://127.0.0.1:8000/v1`, accepts `VLLM_BASE_URL`, and reads the IDs available at `/v1/models`. Jazz selects a sole ID automatically, or asks you to choose among several. On each run it keeps the saved ID if still served, and otherwise uses the first live ID and its context window. Use a chat-capable model and configure tool calling on the server if the agent uses tools; the model list does not reveal whether the server's tool parser is enabled. See [vLLM setup](../configure/providers.md#vllm). For SGLang, choose `sglang`. It defaults to `http://127.0.0.1:30000/v1`, accepts `SGLANG_BASE_URL`, and uses the same live-model selection pattern. Its `/v1/models` cards report the served `max_model_len` for the base model; LoRA adapters inherit that window when their own card omits it. Configure the server's tool and reasoning parsers for the model you load. See [SGLang setup](../configure/providers.md#sglang). Jazz refreshes the served model and context window at the start of each run. For llama.cpp, the loaded model takes precedence over the saved agent model name. Setting `llm.numCtx` limits Jazz's context accounting; it does not reconfigure the server. ## Offline mode With `JAZZ_OFFLINE=1` (or `true`), Jazz skips these product-service requests: - **No update check**: the periodic npm registry version check is skipped (equivalent to `JAZZ_DISABLE_UPDATE_CHECK=1`). - **No models.dev fetch**: the model catalog (used for cloud-provider model lists and metadata enrichment like context windows and pricing) is not fetched. Jazz uses the configured catalog URL’s on-disk snapshot if one exists from a previous online run (`~/.jazz/cache/models-dev.json` for the default catalog), and otherwise falls back to provider-reported metadata and defaults. - **No library fetch**: `jazz persona browse`, `jazz workflow browse` and `jazz skill browse` read the snapshots at `~/.jazz/cache/persona-registry.json`, `~/.jazz/cache/workflow-registry.json` and `~/.jazz/cache/skill-registry.json` from a previous online run, and error if there is none. Installing from the library is refused offline. Point `JAZZ_LIBRARY_URL` at an internal library, with `JAZZ_OFFLINE` unset, to browse and install inside the airgap. It does **not** block inference, `web_fetch`, `http_request`, remote MCP, OTLP export, or a command the agent runs. In an air-gapped deployment, use a local provider, disable OTLP export, omit network-capable tools and MCP servers, and enforce egress at the OS, container, or firewall boundary. ## Model catalog options Ollama, llama.cpp, vLLM, and SGLang agents work with no catalog at all: model lists come from the local server. Ollama's `/api/show` and llama.cpp's `/props` provide additional capability and context metadata; vLLM and SGLang use `/v1/models` for current IDs and context lengths. For an uncatalogued vLLM or SGLang model, Jazz allows tool configuration, but that does not confirm the server is set up to execute tool calls. If you want catalog metadata (e.g. pricing display for cloud models) inside the airgap, either: - **Seed the snapshot**: run Jazz once with network access (or copy `~/.jazz/cache/models-dev.json` from another machine). Every successful catalog fetch refreshes this snapshot, and offline mode reads it automatically. - **Mirror internally**: host a copy of `https://models.dev/api.json` on your network and set `JAZZ_MODELS_DEV_URL=http://mirror.internal/api.json` (leave `JAZZ_OFFLINE` unset so Jazz fetches from the mirror). Each mirror keeps its own snapshot at `~/.jazz/cache/models-dev..json`. Keep the same `JAZZ_MODELS_DEV_URL` when switching to offline mode; Jazz reads only that source’s snapshot and never substitutes a catalog from another URL. A snapshot without a source identifier from an older Jazz version is used only for the default catalog. ## Other network surfaces to know about - **Web tools**: the `web_search` tool requires a configured search provider API key and will simply error without one; `web_fetch` and `http_request` reach whatever URL the agent targets: inside an airgap they can still hit internal services, which is often desirable. Network enforcement should ultimately live at the firewall. - **MCP servers**: stdio servers run locally; HTTP servers connect to the URL you configure. - **Telemetry**: NDJSON is always local under `~/.jazz/telemetry`; if an OTLP endpoint is configured, Jazz also exports to it. Leave OTLP unconfigured or set `telemetry.otlp.enabled` to `false` for a local-only deployment. ## Environment variable reference | Variable | Effect | | --------------------------- | --------------------------------------------------------------------------------------- | | `JAZZ_OFFLINE` | `1`/`true`: skip update checks, the models.dev fetch, and the library fetch entirely | | `OLLAMA_BASE_URL` | Ollama server URL (default `http://127.0.0.1:11434/api`; `/api` appended automatically) | | `LLAMACPP_BASE_URL` | llama.cpp server URL (default `http://127.0.0.1:8080/v1`) | | `VLLM_BASE_URL` | vLLM server URL (default `http://127.0.0.1:8000/v1`) | | `SGLANG_BASE_URL` | SGLang server URL (default `http://127.0.0.1:30000/v1`) | | `JAZZ_MODELS_DEV_URL` | Internal mirror for the models.dev catalog | | `JAZZ_LIBRARY_URL` | Base URL of the persona, workflow, and skill library (default the public Jazz site) | | `JAZZ_DISABLE_UPDATE_CHECK` | `1`: skip only the update check | | `JAZZ_HOME` | Data directory (default `~/.jazz`): holds the catalog snapshot, history, telemetry | --- ## Quick start Source: https://lvndry.github.io/jazz/docs/getting-started/quick-start.md # Quick start ## 1. Install the CLI The install script downloads a self-contained binary for macOS or Linux. No runtime is required. On Windows, run it inside [WSL2](https://learn.microsoft.com/windows/wsl/install). ```bash curl -fsSL https://github.com/lvndry/jazz/releases/latest/download/install.sh | bash ``` The binary installs to `~/.local/bin`. If the installer reports that this directory is missing from your `PATH`, follow its instructions before continuing. ## 2. Create your first agent Open a terminal in a project directory or a folder of files you want Jazz to work with: ```bash jazz ``` On first run Jazz welcomes you, lists any provider API keys it found in your environment, and asks whether to turn on desktop notifications. Choose **Start setup** to pick a provider and model, select a persona, and name your agent. For a hosted provider, supply its API key when asked; [Model providers](../configure/providers.md) explains how to get credentials. Jazz opens a conversation when setup finishes. On later runs, `jazz` shows your agents and a message box. Pick an agent and type a message to start a conversation, or use `/resume` to continue an earlier one. To open a specific agent directly, run `jazz agent chat `. Jazz is free and MIT-licensed. Model providers may charge for usage. To start without a paid API model: - **Start using Jazz for free**: choose [OpenRouter](https://openrouter.ai) and the [`Free Models Router`](https://openrouter.ai/openrouter/free) model. No credit card. - **Run locally**: start [Ollama with a tool-capable model](./local-models.md), then choose `ollama` during setup. ## 3. Give it a task During setup, choose the `default` persona and name your agent `assistant`. The conversation opens automatically. Try this prompt: ```text Read the files in this directory and explain what this project does. List the main parts and how to get started. Do not change any files. ``` Jazz shows the tools the agent calls as it reads. You can ask follow-up questions in the same conversation, or give it a task such as: ```text Write a GETTING-STARTED.md based on what you found. Include the setup commands and explain how to run the project. ``` When Jazz asks for approval, review the proposed change and approve or reject it. You can continue refining the result in the same conversation. To return later, run `jazz` and enter `/resume`. ## 4. Update Jazz ```bash jazz update ``` Before updating across a minor version, read [Upgrading](../upgrading.md): it explains the versioning policy and what to change when a release renames a setting. ## Other installation options Override the installation directory with `JAZZ_INSTALL_DIR`, or pin a version with `JAZZ_VERSION`: ```bash curl -fsSL https://github.com/lvndry/jazz/releases/latest/download/install.sh | JAZZ_VERSION=v0.15.21 JAZZ_INSTALL_DIR="$HOME/bin" bash ``` Jazz is also on npm, which installs the same macOS or Linux binary through your package manager: ```bash # npm npm install -g jazz-ai # bun (--trust lets the postinstall script fetch the platform binary) bun add -g --trust jazz-ai # pnpm pnpm add -g jazz-ai # yarn yarn global add jazz-ai ``` `jazz update` upgrades either kind of installation: a binary replaces itself from the GitHub release, and a package install goes back through the package manager that put it there. Windows is not supported natively, by the installer or by npm. Install Jazz inside [WSL2](https://learn.microsoft.com/windows/wsl/install) with the `curl` command above; it behaves there as it does on any Linux machine. ### Verify where a binary came from The checksum check proves the download is intact. To prove it was built by this repository's release workflow, check its build provenance with the GitHub CLI. Release binaries with signed attestations can be checked as follows: ```bash tag="v$(jazz --version)" gh release download "$tag" --repo lvndry/jazz --pattern 'jazz-darwin-arm64.gz' gh attestation verify jazz-darwin-arm64.gz --repo lvndry/jazz ``` Swap in the asset for your platform (`jazz-linux-x64.gz`, `jazz-linux-arm64-musl.gz`, and so on). ## Next steps - **[CLI](../surfaces/cli.md)**: conversations, attachments, approvals, and run controls - **[CLI reference](../commands.md)**: all commands and flags - **[Creating agents](./create-an-agent.md)**: configure one for a specific job - **[Surfaces](../surfaces/index.md)**: run the same agent headless, on a schedule, in CI, or in a chat thread - **[Guides](../guides/index.md)**: copy-pasteable recipes - **[Concepts](../concepts/index.md)**: learn the vocabulary behind Jazz --- ## Uninstalling Jazz Source: https://lvndry.github.io/jazz/docs/getting-started/uninstall.md # Uninstalling Jazz Jazz has no uninstall command. Remove things in this order, so nothing keeps firing a binary that is gone: schedules first, then services, then secrets, then data, then the binary. If you used `JAZZ_HOME` or `--data-dir` for more than one home, repeat the steps that mention `~/.jazz` for each home. ## 1. Scheduled workflows List what is scheduled, then remove each one: ```bash jazz workflow scheduled jazz workflow unschedule ``` On macOS each schedule is a launchd job in `~/Library/LaunchAgents/com.jazz.workflow.*.plist`; on Linux it is a crontab line below a `# Jazz schedule:` comment. Check that none are left: ```bash ls ~/Library/LaunchAgents/com.jazz.* 2>/dev/null # macOS crontab -l | grep -A1 '# Jazz' # Linux ``` ## 2. Reminders and wake-ups Reminders and wake-ups an agent set are one-shot jobs. Ask the agent to cancel them, or remove them by hand: ```bash # macOS for plist in ~/Library/LaunchAgents/com.jazz.reminder.*.plist ~/Library/LaunchAgents/com.jazz.trigger.*.plist; do [ -e "$plist" ] || continue launchctl unload "$plist" rm "$plist" done # Linux: they are `at` jobs atq atrm ``` ## 3. The daemon Stop a daemon you started yourself, and remove the system service if you installed one: ```bash jazz daemon stop sudo jazz daemon uninstall ``` `jazz daemon uninstall` removes `/Library/LaunchDaemons/com.jazz.daemon.plist` on macOS or `/etc/systemd/system/jazz-daemon.service` on Linux, and the `/etc/jazz/daemon.env` file beside it. ## 4. Chat bots - **iMessage on your Mac:** run `jazz imessage stop`, then remove `~/Library/LaunchAgents/com.github.lvndry.jazz.imessage.plist` and the bridge's data in `~/.jazz-imessage`. - **iMessage through Photon:** remove `~/.jazz-photon`. - **WhatsApp:** unlink the device in WhatsApp (**Settings → Linked devices**), then remove `~/.jazz-whatsapp`, which holds the link keys. - **Telegram and Discord:** stop the containers (`docker compose down` in the bot's directory), remove the `auto-update.sh` cron line if you added one, and delete the data volume. See [Reaching your agent from a chat app](../guides/deploy-a-chat-agent.md). ## 5. Keyring entries API keys, tokens and sign-ins live in the OS keyring, in one entry per Jazz home. Its service is `jazz..vault` and its account is `secrets`. Entries written by older versions use the service `jazz` or `jazz.`, one per setting; Jazz moves them into the vault on first run. ```bash # macOS: list the entries, then delete each one by its service ("svce") and account ("acct") security dump-keychain | grep -B4 -A4 '"svce"="jazz' security delete-generic-password -s -a # Linux: list the vault entries, then clear each secret-tool search --all account secrets secret-tool clear service account ``` On a host without a keyring, secrets are in `~/.jazz/secrets.json`, which the next step removes. ## 6. Data and configuration Everything else Jazz keeps (config, agents, conversations, memory, logs, caches and the unpacked runtime) is in one directory: ```bash rm -rf ~/.jazz ``` [Runtime data](../runtime-data/index.md) lists what is in it, if you want to keep a copy of your agents or conversations first. A project's own `./.jazz/config.json` is only removed if you delete it. Two more locations are shared with other tools, so check them before deleting: - `~/.agents/mcp.json` holds the MCP servers `jazz mcp add` wrote. Remove Jazz's entries with `jazz mcp remove `, or delete the file if nothing else uses it. - `~/.agents/skills/` holds skills other agents may also read. Jazz only reads it. ## 7. The binary Remove it the way you installed it: ```bash rm ~/.local/bin/jazz # install script (or wherever JAZZ_INSTALL_DIR pointed) npm rm -g jazz-ai # npm bun rm -g jazz-ai # bun pnpm rm -g jazz-ai # pnpm yarn global remove jazz-ai # yarn ``` `which -a jazz` should then print nothing. --- ## CLI reference Source: https://lvndry.github.io/jazz/docs/commands.md # 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 ` | none | The time zone the user is in, such as `Europe/Paris`, used to resolve clock times for reminders and wake triggers. Without it the agent asks the user for their zone before scheduling a clock time. | | `--timezone-source ` | `user-config` | Where `--timezone` came from: `chat-setting`, `user-config` or `operator-default`. Shown to the agent so it can state its assumption. | | `--zone-setting-command ` | none | The command a user sends to remember their zone on this surface, such as `/tz`. The agent offers it when it asks for a zone. | | `--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) and the loop keeps that zone by name, so moving the machine to another zone does not move the schedule. 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 resolved` | Show every effective setting and the layer it came from; `--json` prints one JSON document | | `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 | | `jazz config refresh-chatgpt` | Refresh the ChatGPT sign-in unless its access token stays valid `--min-valid-minutes`, then check the token works | `config resolved` reads the config files, the environment and `--debug` without starting the daemon, reading the keyring or using the network, so it works on a machine with nothing configured. [Read where a setting came from](./configure/jazz.md#see-where-each-setting-came-from). `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. `config refresh-chatgpt --min-valid-minutes ` is for hosted runners that share one ChatGPT sign-in between parallel runs. Run it in one serialized step with `JAZZ_CHATGPT_CREDENTIAL` and `JAZZ_CHATGPT_CREDENTIAL_OUTPUT`: it refreshes under the credential lock only when the access token would expire within that many minutes, makes one authenticated request to prove the token works (a refused token is refreshed once), and prints the expiry, never a token. SIGINT and SIGTERM wait until it finishes, so an interrupted refresh cannot lose the rotated refresh token. The parallel runs then receive the access token through `JAZZ_CHATGPT_ACCESS_TOKEN`, which never refreshes. See [ChatGPT subscription](./configure/providers.md#chatgpt-subscription). 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 refresh-chatgpt` | `--min-valid-minutes ` | Required. Refresh unless the access token stays valid at least this long | | `jazz config resolved` | `--json` | Print one JSON document | | `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