Skip to main content
The publishable package is @wzrdtech/zap; it exposes the zap binary.

​
Install and invoke

Use Node 24.x. For one-off commands:
After a project-local install, invoke the binary with npm exec:
Or install globally:

​
Commands

  • zap add <registry-name> [--force] [--json] — Add a registry Zap.
  • zap agent <new|ls|render|lint> [--json] — Scaffold, list, render, and lint agents-as-code.
  • zap compose [Runtime.md|zap.config.ts] [--dry-run] [--json] — Resolve Runtime.md or zap.config.ts into the runtime plugin tree.
  • zap deploy <slug|Zap.md> [--finalize] [--json] — Upload a draft Zap to the hosted API. The flag form (--watch, --alias, --agent, --all) deploys agents.
  • zap dev — Start the web app dev server.
  • zap docs [topic] [--json] — Print bundled docs.
  • zap doctor [--json] — Check local setup.
  • zap embed <slug> [--base-url https://zap.wzrd.tech] [--json] — Print iframe/oEmbed embed snippets.
  • zap feedback <message> [--json] — Store local feedback.
  • zap ffmpeg <preset> <input> <output> [--live] [--json] — Plan (default) or run ffmpeg presets against local media.
  • zap finalize <slug> [--token ...] [--api-url ...] [--json] — Finalize a deployed draft into the gallery.
  • zap fs <ls|read|write|rm> <runtime-id> <path> [content] [--json] — Runtime filesystem operations.
  • zap gallery [--remote] [--json] — List local recipes; add --remote for the hosted gallery.
  • zap harness <ls|bake <template>|doctor <id|template>|run <template> --prompt <p>> [--live] [--json] — List, bake, doctor, and run zap-heavy harness templates.
  • zap import <hyperframes|openmontage> [--source path] [--limit n] [--force] [--json] — Import template registries.
  • zap improve <slug|Zap.md> [--json] [--write] — Propose a version bump from run and feedback evidence.
  • zap info [--json] — Print environment info.
  • zap init <directory> [--non-interactive] [--empty] [--example <slug>] [--json] — Create a lightweight Zap project.
  • zap inspect <slug|Zap.md> [--json] — Show provider/model plan details.
  • zap keys [add|list|test|remove|sync] [--json] — Manage encrypted BYOK provider keys.
  • zap lint [Zap.md ...] [--json] — Run recipe policy checks.
  • zap login --token <token> [--api-url ...] | zap login --provider <id> [--json] — Store a Zap API token, or device-auth via --provider.
  • zap logout [--json] — Remove the stored Zap API token.
  • zap mcp [--http [--host 127.0.0.1] [--port 3910]] [--json] — Start the Zap MCP server (stdio by default, --http for Streamable HTTP).
  • zap media <ls|info> [path] [--json] — Inspect local media outputs.
  • zap memory <status|search|export|forget> [--json] — Query and manage runtime memory.
  • zap new <slug> [--force] [--json] — Scaffold agent/skills/zap-<slug>.
  • zap pay <status|login|logout|quote> [--json] — Payer status, managed wallet login/logout, and payment quotes.
  • zap run <slug|Zap.md> [--input KEY=VALUE] [--budget-cap-usd N] [--live] [--json] — Plan a Zap by default; use --live to submit providers.
  • zap runtime <up|down|ps|logs|exec|snapshot|fork|stop|resume|desktop|import-sprite> [...] [--json] — Manage Zap runtimes.
  • zap search <query> [--remote] [--json] — Search registry templates.
  • zap secret <set|list|remove|sync> [NAME] [--agent <id>] [--env <alias>] [--stdin] [--json] — Set, list, remove, and sync write-only agent secrets.
  • zap session --agent <id>[@<alias>] [--session <id>] [--live] [--verbose|--json] "..." — Run a turn against a durable agent session (plan-only by default).
  • zap sessions ls [--json] — List durable agent sessions.
  • zap skills [generate|update|check] [--json] — Generate or check the skills manifest.
  • zap status [runId] [--json] — Show local run status.
  • zap studio — Start the web studio.
  • zap telemetry [on|off|status] [--json] — Manage local telemetry preference.
  • zap template <ls|show> [name] [--json] — List or show runtime templates.
  • zap upgrade [--json] — Print upgrade guidance.
  • zap validate [Zap.md ...] [--json] — Validate one or more recipes.

​
Runtime workflow

  • zap compose [Runtime.md|zap.config.ts] --dry-run --json resolves a runtime definition into its deterministic plugin tree without acquiring anything. Equivalent Runtime.md and zap.config.ts definitions produce identical trees and lock hashes.
  • zap runtime up|down|ps|logs|exec|snapshot|fork|stop|resume|desktop|import-sprite manages runtime lifecycles. zap runtime exec <id> --prompt ... counts as spend and requires a payer.
  • zap fs <ls|read|write|rm> <runtime-id> <path> operates on a runtime’s filesystem.
  • zap ffmpeg <preset> <input> <output> prints the ffmpeg plan by default; --live executes it and requires a payer.

​
Recipe workflow (preserved from 0.3.1)

  • zap run <Zap.md> performs a zero-spend plan by default.
  • zap run <Zap.md> --live submits live provider work with locally stored BYOK keys. Live runs require a payer; without one they fail with PAYER_MISSING.
  • zap run <Zap.md> --budget-cap-usd <n> overrides the recipe spend cap for that run.

​
Auth

  • zap login --token <token> stores the Zap API token under the apiToken key of .zap/auth.json.
  • zap login --provider <id> runs provider device auth (OpenAI/Codex and Claude Code flows).
  • zap logout clears only the API token; managed-payer credentials are cleared by zap pay logout.

​
Machine-readable output and errors

Every command supports --json. Failures with --json print a structured error object and exit non-zero. See JSON output shapes. Exit codes: 0 success, 1 failure, 2 usage error.

​
Safety defaults

CLI runs are plan-only unless --live is provided, and every live/spending path requires a configured payer. Telemetry is off unless you explicitly run zap telemetry on.