Documentation Index
Fetch the complete documentation index at: https://mintlify.com/gratitude5dee/Zap/llms.txt
Use this file to discover all available pages before exploring further.
In this guide you will scaffold a fresh Zap project, author a recipe with zap new, validate it against the schema, and execute the full pipeline in mock mode — producing a local run result with no provider spend. The whole sequence takes under five minutes and requires only Node.js 24 and an internet connection for the initial npx fetch.
Install & scaffold a project
Run the init command with --non-interactive to scaffold the project layout, write AGENTS.md, .env.example, and package.json, and install a sample hello-world recipe — then install dependencies:npx @wzrdtech/zap@0.1.0 init demo --non-interactive
cd demo
npm install
package.json includes a full set of convenience scripts so you can use npm run zap:* instead of typing the full npx prefix each time. Scaffold a recipe
Use zap new to scaffold a recipe skill directory. The slug is lowercased and hyphenated automatically:npx @wzrdtech/zap@0.1.0 new my-zap
agent/
└── skills/
└── zap-my-zap/
├── SKILL.md
├── Zap.md
└── prompts/
├── initial-frame.md
└── initial-gen.md
Zap.md has pre-filled frontmatter ready to validate and run immediately:---
budget:
cap_usd: 5
estimate_usd: 0
defaults:
provider: mock
description: A one-click My Zap content recipe.
inputs:
PROMPT:
hint: Describe the scene or transformation.
label: Prompt
required: true
type: textarea
output: Zap.mp4
steps:
- id: initial_frame
kind: image.gen
model: mock-image
prompt: prompts/initial-frame.md
provider: mock
- duration_s: 15
id: initial_gen
inputs:
- initial_frame
kind: video.gen
model: mock-video
prompt: prompts/initial-gen.md
provider: mock
- id: stitch
inputs:
- initial_gen
kind: stitch
stitch:
engine: auto
format: mp4
quality: standard
version: 1
zap: my-zap
---
# My Zap
Validate the recipe
Run the validator to confirm the frontmatter schema is correct, all step id and kind fields are present, input references are declared, and the budget cap is positive:npx @wzrdtech/zap@0.1.0 validate
ok agent/skills/zap-my-zap/Zap.md (my-zap)
zap validate agent/skills/zap-my-zap/Zap.md. Run the mock pipeline
Execute the full step graph in mock mode. The --json flag returns machine-readable output suitable for agents and CI pipelines:npx @wzrdtech/zap@0.1.0 run agent/skills/zap-my-zap/Zap.md --json
{
"runId": "run_lx0k3f_a1b2c3",
"zap": "my-zap",
"status": "done",
"mode": "mock",
"live": false,
"message": "Mock Zap run completed.",
"quoteUsd": 0,
"zapUrl": "mock://zap/my-zap/run_lx0k3f_a1b2c3/Zap.mp4",
"steps": [
{ "stepId": "initial_frame", "kind": "image.gen", "provider": "mock", "status": "done", "quoteUsd": 0 },
{ "stepId": "initial_gen", "kind": "video.gen", "provider": "mock", "status": "done", "quoteUsd": 0 },
{ "stepId": "stitch", "kind": "stitch", "provider": "mock", "status": "done", "quoteUsd": 0 }
]
}
.zap/runs/<runId>/result.json for offline inspection. Check run status
List all local runs or inspect a specific run by ID:# List all run IDs
npx @wzrdtech/zap@0.1.0 status
# Inspect a specific run
npx @wzrdtech/zap@0.1.0 status run_lx0k3f_a1b2c3
run_lx0k3f_a1b2c3 done mock://zap/my-zap/run_lx0k3f_a1b2c3/Zap.mp4
Live provider runs require --live plus provider credentials. Mock mode is always the default and always free. To run against real providers (GMI Cloud, fal.ai, etc.), pass --live and ensure the appropriate API keys are set in your environment. See Providers for key names and setup instructions. Use the npm scripts for daily development. zap init adds these scripts to package.json automatically:{
"scripts": {
"zap:new": "zap new",
"zap:validate": "zap validate",
"zap:run": "zap run",
"zap:status": "zap status",
"zap:doctor": "zap doctor",
"zap:docs": "zap docs",
"zap:skills": "zap skills check"
}
}
npm run zap:validate, npm run zap:run -- agent/skills/zap-my-zap/Zap.md --json, and so on without the npx @wzrdtech/zap@0.1.0 prefix. 