baz CLI — Mandatory Video Generation Workflow

Use this skill when the user wants to create, edit, or export videos using the Bazaar CLI (baz).

This is a GATED workflow. You MUST complete each phase in order. Do NOT skip phases. Do NOT declare "done" until the completion checklist at the bottom passes.

---

Getting Started (New Agents)

If you don't have a Bazaar account or API key yet, register programmatically:

# 1. Discover what Bazaar can do
curl https://bazaar.it/api/v1/capabilities

# 2. Register (one POST, no human needed)
curl -X POST https://bazaar.it/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email":"your-agent@example.com","name":"My Agent"}'
# Returns: api_key, auth header name, quickstart steps, endpoint URLs

# 3. Save your API key — authenticate all future requests with:
#    -H "x-api-key: <your-api-key>"

# 4. Check pricing before you start
curl https://bazaar.it/api/v1/pricing

# 5. Install the CLI
npm install -g bazaar.it
baz auth login <your-api-key>

Balance starts at $0. When you hit a paid operation, you'll get HTTP 402 with a top_up_url in the response body. Call POST /api/v1/top-up with {"amount_cents": 500} (minimum $5) to get a Stripe checkout URL.

Shortcut: If your human creates an account at bazaar.it, they get $4 to start with. Ask them to grab an API key from the dashboard and you can skip straight to step 5.

Already have an API key? Skip to Phase 1.

---

When to Use

• User asks to create, edit, or export videos via CLI
• User wants to automate video generation
• User mentions "baz", "bazaar CLI", or "video generation from terminal"

When to Use baz prompt vs Spar

• Direct baz prompt — Scene creation, edits, full agent orchestration
• baz prompt --spar — Planning-only conversation (no timeline mutations)

---

Phase 1: Context (REQUIRED — do NOT skip)

You MUST set project context BEFORE generating any scenes. This gives the composition agent the information it needs to produce correct output on the first try.

Minimum context required:

1. Goal — What is this video for? Who is the audience? What should they feel/do?
2. Requirements — Specific, verifiable things the video must contain
3. Brand — Colors, fonts, logo placement, visual style

# Create or select project
baz project create --name "Descriptive Name - Date/Purpose" --json
# OR
baz project use <id>

# Set goal (be specific — audience, purpose, desired outcome)
baz context add "Create 45-60 second feature announcement for [Product]. \
Audience: [who]. Key value: [what they get]." --label "goal"

# Add requirements (each one should be independently verifiable)
baz context add "Show [specific feature interaction]" --label "requirement"
baz context add "Include CTA: '[specific text]'" --label "requirement"
baz context add "Total duration: [range]" --label "requirement"

# Set brand guidelines
baz context add "Brand: [Name]. Primary [hex], accent [hex]. Font: [name]. \
[Logo placement]. [Visual style notes]." --label "brand"

Verify context is set:

baz context list --json

Gate: Do NOT proceed to Phase 2 until baz context list shows at least one goal, one requirement, and one brand entry.

---

Phase 2: Generate

Now prompt the agent to create scenes. You can use one big prompt or multiple scene-by-scene prompts.

# Option A: One comprehensive prompt
baz prompt "Create a video with: [scene 1 description], [scene 2], ..." --stream-json

# Option B: Scene-by-scene (more control)
baz prompt "Scene 1 (5s): Dark gradient intro, logo top-left, title slides up" --stream-json
baz prompt "Scene 2 (7s): Problem statement with mock UI..." --stream-json
baz prompt "Scene 3 (18s): Feature walkthrough..." --stream-json

Tips:

• Include duration in each prompt
• Be specific about animations, colors, layout
• Reference brand context set in Phase 1

Choreography (REQUIRED for 3+ scene videos)

For videos with 3 or more scenes, plan choreography BEFORE generating. This prevents the "lockstep slideshow" pattern where all layers swap at the same frame boundary.

Actor Planning Template

Before prompting, plan your actors:

5 Prompt Enrichment Rules

1. Every content prompt includes exit instructions (exempt: persistent backgrounds, final CTA)
2. Prefer ONE background on Track 0 for the full video duration
3. Every overlay prompt includes position and size — scenes that share screen time must not share screen space
4. Specify spring animation for hero elements (spring() for hero entrance)
5. Include energy level hints in prompts ("high energy entrance", "calm sustained section")

GOOD Example — context injection + one natural prompt:

baz context add "CHOREOGRAPHY: Every overlay scene must specify its position and size. \
  Use spring() for hero elements. Every non-final scene must have exit animations. \
  Prefer one continuous background." --label "instructions"

baz prompt "Create a 15-second product demo: dark theme intro with logo, \
  feature showcase with 3 cards, area chart showing growth, and a CTA. \
  Brand: #6366f1 purple, #10b981 green, Inter font." --stream-json

ONE natural prompt. The composition agent handles decomposition into tracks + spatial layout internally based on choreography context.

---

Phase 3: Review & Verify (REQUIRED — NEVER skip)

After generation, you MUST run both review and verify. This is not optional.

Step 1: Review

baz review --json

Read the output. Compare every requirement from Phase 1 against what was generated.

Step 2: Verify

baz verify --criteria "requirement 1,requirement 2,requirement 3" --json

Pass ALL requirements from Phase 1 as comma-separated criteria. The verify command checks each one.

Interpret results:

{
  "passedAll": true,
  "results": [
    { "criteria": "...", "passed": true },
    { "criteria": "...", "passed": false, "reason": "..." }
  ]
}

Gate: If passedAll: false, you MUST proceed to Phase 4. Do NOT export. Do NOT declare done.

---

Phase 4: Iterate (REQUIRED if Phase 3 fails)

Fix every failing criteria. Then re-verify.

LOOP:
  1. Read failing criteria from Phase 3
  2. Fix with: baz prompt "Fix: [specific issue]" --stream-json
  3. Re-run: baz review --json
  4. Re-run: baz verify --criteria "req1,req2,req3" --json
  5. If passedAll: false → GOTO 1
  6. If passedAll: true → proceed to Phase 5

Do NOT exit this loop until passedAll: true.

---

Phase 5: Export (only if requested)

Only export if the user explicitly asked for a rendered video AND Phase 3/4 passed.

baz export start --wait --json

---

Command Quick Reference

Error Handling

---

Completion Checklist

You are NOT done until ALL of these are true:

• Phase 1: baz context list shows goal + requirements + brand
• Phase 2: Scenes generated via baz prompt
• Phase 3: baz review --json run AND baz verify --criteria "req1,req2,..." --json run
• Phase 4: passedAll: true (or was true on first verify)
• Phase 5: Export started (only if user requested it)

If you skipped review/verify, you are not done. Go back and run them.

---

External Endpoints

Security & Privacy

• Authentication: All non-discovery endpoints require x-api-key header
• Data sent: Your prompts, project metadata, and scene code are sent to Bazaar servers for AI processing
• Data stored: Projects, scenes, and generated assets are stored on Bazaar's infrastructure (Neon DB + Cloudflare R2)
• No local file access: This skill only uses the baz CLI binary — it does not read or modify local files beyond CLI config at ~/.bazaar/config.json
• Balance: Operations consume dollar balance. Check baz auth status to see remaining balance before large jobs
• Exports: Rendered videos are stored on Bazaar CDN and accessible via URL

Web UI Access

Your human can also edit the project directly in the browser at: https://bazaar.it/projects/<project-id>/generate

After creating a project, share this link so they can preview scenes, tweak code, or make manual edits alongside your CLI workflow.