> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zap.wzrd.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# Zap CLI Global Flags: Shared Options Across All Commands
> Reference for all Zap CLI flags: --json for machine-readable output, --live for provider spend, --input for recipe values, and --force.
The Zap CLI uses a consistent flag syntax across all commands. Most flags that control output format or execution mode work on any command that produces output. Flags are parsed uniformly: they accept `--key value`, `--key=value`, or bare `--key` for boolean flags. Flags can appear before or after positional arguments.
***
## Flag Reference
Emit JSON to stdout instead of human-readable text. All commands that produce output support this flag. Useful for agent consumption, scripting, and piping output to other tools. When set, error messages are still printed to stderr in plain text with a `zap:` prefix.
```bash theme={null}
zap validate --json
zap run agent/skills/zap-my-zap/Zap.md --json
zap doctor --json
```
Allow real provider spend on the `run` command. Without this flag, `run` executes in mock mode: no external API calls are made, all steps resolve instantly, and `quoteUsd` is `0`. With `--live`, the CLI computes a real spend quote from per-model rates and rejects the run if the quote exceeds `budget.cap_usd`.
```bash theme={null}
zap run agent/skills/zap-my-zap/Zap.md --live --input PROMPT="sunset"
```
A live run sets `status: "queued"` and requires provider API keys to be configured. Use the web runtime to submit and monitor provider jobs.
Provide a recipe input value as a `KEY=VALUE` pair. This flag is repeatable — pass it multiple times to supply multiple input values. Input keys must match a declared entry in the recipe's `inputs` map.
```bash theme={null}
zap run agent/skills/zap-my-zap/Zap.md \
--input PROMPT="sunset over mountains" \
--input STYLE="cinematic"
```
In mock mode, required inputs that are not supplied receive placeholder defaults:
* Text inputs default to `mock-` (e.g. `mock-prompt`)
* Image inputs default to `mock://input/` (e.g. `mock://input/IMAGE`)
Number of `video.extend` step repetitions for the `run` command. Overrides the `repeat.default` value declared in the recipe. The final count is clamped between `repeat.min` and `repeat.max`.
```bash theme={null}
zap run agent/skills/zap-my-zap/Zap.md --extend 3
```
Overwrite existing files on `new` and `add` commands. Without this flag, both commands throw an error if any destination file already exists.
```bash theme={null}
zap new my-zap --force
zap add zap-world-cup-entrance --force
```
Skip interactive prompts on the `init` command. Use this flag in CI pipelines or scripted project setup where stdin is unavailable.
```bash theme={null}
zap init my-app --non-interactive
```
Skip sample recipe scaffolding on the `init` command. Creates the project structure (`agent/skills/`, `docs/`, `.zap/`, etc.) without generating a starter `Zap.md` recipe.
```bash theme={null}
zap init my-app --empty
```
Use a named example recipe during `init`. The named recipe is scaffolded instead of the default `hello-world` starter.
```bash theme={null}
zap init my-app --example world-cup-entrance
```
Print the CLI version and exit. Can also be invoked as `zap --version` before any command.
```bash theme={null}
zap --version
# 0.1.0
```
Print the help text listing all commands and common flags, then exit. Also triggered by `zap help` or running `zap` with no arguments.
```bash theme={null}
zap --help
zap help
```
***
## Flag Syntax Rules
The parser accepts three equivalent forms for any named flag:
```bash theme={null}
# Space-separated value
zap run Zap.md --input PROMPT=hello
# Equals-separated value
zap run Zap.md --input=PROMPT=hello
# Bare boolean flag
zap run Zap.md --live
```
**Repeating a flag** collects values into an array. This is used by `--input` to supply multiple recipe inputs:
```bash theme={null}
zap run Zap.md --input PROMPT="text" --input STYLE="cinematic"
```
Flags can appear before or after positional arguments:
```bash theme={null}
# These are equivalent:
zap run Zap.md --json --live
zap run --json --live Zap.md
```
***
## Environment Variable Overrides
Several CLI behaviors can be controlled through environment variables, useful for CI and Docker environments:
| Variable | Effect |
| ------------------------------- | ----------------------------------------------------------------- |
| `ZAP_LINT_ALLOW_LIVE_DEFAULT=1` | Silence the `zap lint` warning about non-mock `defaults.provider` |
This can be set in your `.env` or `.env.local` file (automatically loaded by the CLI on startup) or exported in your shell:
```bash theme={null}
ZAP_LINT_ALLOW_LIVE_DEFAULT=1 zap lint
```
***
## JSON Output Schema
When `--json` is passed to the `run` command, the output follows this schema:
```json theme={null}
{
"live": false,
"message": "Mock Zap run completed.",
"mode": "mock",
"quoteUsd": 0,
"runId": "run_m3x9k2_a1b2c3",
"status": "done",
"steps": [
{
"kind": "image.gen",
"model": "mock-image",
"provider": "mock",
"quoteUsd": 0,
"status": "done",
"stepId": "initial_frame"
},
{
"kind": "video.gen",
"model": "mock-video",
"provider": "mock",
"quoteUsd": 0,
"status": "done",
"stepId": "initial_gen"
},
{
"kind": "stitch",
"model": "local",
"provider": "mock",
"quoteUsd": 0,
"status": "done",
"stepId": "stitch"
}
],
"zap": "my-zap",
"zapUrl": "mock://zap/my-zap/run_m3x9k2_a1b2c3/Zap.mp4"
}
```
**Field descriptions:**
| Field | Type | Description |
| ---------- | ---------------------- | ------------------------------------------------------------------------------------------ |
| `live` | boolean | Whether this was a live or mock run |
| `message` | string | Human-readable status message |
| `mode` | `"mock"` \| `"live"` | Execution mode |
| `quoteUsd` | number | Total estimated spend in USD (always `0` in mock mode) |
| `runId` | string | Unique run identifier; also the directory name under `.zap/runs/` |
| `status` | `"done"` \| `"queued"` | `"done"` for mock runs; `"queued"` for live runs awaiting web runtime |
| `steps` | array | Per-step execution detail (see below) |
| `zap` | string | The recipe slug |
| `zapUrl` | string \| undefined | Output URL; populated for mock runs; omitted for live runs until the web runtime completes |
**Step object fields:**
| Field | Type | Description |
| ---------- | ------ | -------------------------------------------------- |
| `kind` | string | Step type, e.g. `image.gen`, `video.gen`, `stitch` |
| `model` | string | Model identifier; `"local"` for non-provider steps |
| `provider` | string | Provider name; `"mock"` in mock mode |
| `quoteUsd` | number | Per-step spend estimate; `0` in mock mode |
| `status` | string | Step status |
| `stepId` | string | Step ID from the recipe |
***
## Safety Defaults
The Zap CLI is designed to be safe by default:
All `zap run` executions are mock unless `--live` is explicitly provided. No provider API calls are made and no real money is spent in mock mode.
Telemetry is disabled by default. It must be explicitly enabled by running `zap telemetry on`. The preference is stored locally in `.zap/telemetry.json`.
These defaults ensure that:
* Agents running `zap run` during recipe development do not incur unexpected provider charges
* Users retain full control over whether any usage data is collected
* CI pipelines can safely run `zap validate`, `zap lint`, and `zap skills check` without any credentials or opt-in configuration