Zap CLI Commands: Complete @wzrdtech/zap Reference Guide

# Use directly without installing:
npx @wzrdtech/zap@0.1.0 <command>

# Or install globally:
npm install -g @wzrdtech/zap

zap init <directory> [--non-interactive] [--empty] [--example <name>] [--json]

npx @wzrdtech/zap@0.1.0 init my-app --non-interactive
# Initialized Zap project at /home/user/my-app

# With --json
npx @wzrdtech/zap@0.1.0 init my-app --json

{
  "ok": true,
  "root": "/home/user/my-app"
}

zap new <slug> [--force] [--json]

zap new world-intro
# Created zap-world-intro at agent/skills/zap-world-intro

zap new world-intro --json

{
  "ok": true,
  "skillDir": "/home/user/my-app/agent/skills/zap-world-intro",
  "slug": "world-intro"
}

zap validate [Zap.md|slug] [--json]

zap validate
# ok agent/skills/zap-my-zap/Zap.md (my-zap)
# ok agent/skills/zap-world-intro/Zap.md (world-intro)

zap validate agent/skills/zap-my-zap/Zap.md --json

{
  "results": [
    {
      "file": "agent/skills/zap-my-zap/Zap.md",
      "ok": true,
      "zap": "my-zap"
    }
  ]
}

zap lint [Zap.md|slug] [--json]

zap lint
# ok agent/skills/zap-my-zap/Zap.md (my-zap)
# warn agent/skills/zap-live-test/Zap.md (live-test)
#   - defaults.provider is live; mock is safer for published templates.

zap lint agent/skills/zap-live-test/Zap.md --json

{
  "results": [
    {
      "file": "agent/skills/zap-live-test/Zap.md",
      "ok": false,
      "warnings": [
        "defaults.provider is live; mock is safer for published templates."
      ],
      "zap": "live-test"
    }
  ]
}

zap run <Zap.md|slug> [--live] [--input KEY=VALUE] [--extend <n>] [--json]

zap run agent/skills/zap-my-zap/Zap.md --input PROMPT="sunset over mountains"
# Mock Zap run completed. run_m3x9k2_a1b2c3

zap run agent/skills/zap-my-zap/Zap.md --input PROMPT="sunset over mountains" --json

{
  "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"
}

zap run agent/skills/zap-my-zap/Zap.md --live --input PROMPT="sunset over mountains"
# Live provider run planned. Use the web runtime to submit provider jobs. run_m3x9k2_a1b2c3

zap status [runId] [--json]

zap status
# run_m3x9k2_a1b2c3
# run_m3x8a1_b2c3d4

zap status run_m3x9k2_a1b2c3
# run_m3x9k2_a1b2c3 done mock://zap/my-zap/run_m3x9k2_a1b2c3/Zap.mp4

zap status run_m3x9k2_a1b2c3 --json

{
  "runId": "run_m3x9k2_a1b2c3",
  "status": "done",
  "mode": "mock",
  "zap": "my-zap",
  "zapUrl": "mock://zap/my-zap/run_m3x9k2_a1b2c3/Zap.mp4"
}

zap add <name> [--force] [--json]

zap add zap-world-cup-entrance
# Added zap-world-cup-entrance to agent/skills/zap-world-cup-entrance

zap add world-cup-entrance --json

{
  "ok": true,
  "targetDir": "/home/user/my-app/agent/skills/zap-world-cup-entrance"
}

zap docs [topic] [--json]

zap docs schema
# (prints zap-spec.md to stdout)

zap docs unknown-topic
# agents
# cli
# deploy
# providers
# ...

zap skills [generate|update|check] [--json]

zap skills generate
# Generated skills/skills-manifest.json
# zap-my-zap 5 a1b2c3d4e5f6

zap skills check
# ok skills/skills-manifest.json

zap skills check --json

{
  "differences": [],
  "manifestPath": "/home/user/my-app/skills/skills-manifest.json",
  "ok": true
}

zap doctor [--json]

zap doctor
# ok node: Node 24.1.0
# ok package: package.json present
# ok zap skills: agent/skills present
# ok convex: NEXT_PUBLIC_CONVEX_URL configured
# ok upstash: Upstash REST env configured
# warn supabase: Supabase public env configured
# warn hyperframes: optional HyperFrames CLI available

zap dev

zap studio

zap info [--json]

zap info
# cwd: /home/user/my-app
# node: 24.1.0
# platform: linux x64
# version: 0.1.0

zap info --json

{
  "cwd": "/home/user/my-app",
  "node": "24.1.0",
  "platform": "linux x64",
  "version": "0.1.0"
}

zap upgrade

npm install -g @wzrdtech/zap@latest
# or, for a project dependency:
npm install --save-dev @wzrdtech/zap@latest

zap upgrade
# Upgrade checks are intentionally local in v0.1. Reinstall @wzrdtech/zap to upgrade.

zap feedback <message> [--json]

zap feedback "The mock run output is very helpful"
# Feedback saved locally.

zap telemetry [on|off|status] [--json]

zap telemetry
# Telemetry off

zap telemetry on
# Telemetry on

zap telemetry --json

{
  "enabled": true
}