{"id":"4546b75a-0cf5-44b1-ae76-71a31537f718","shortId":"VArB3e","kind":"skill","title":"wonda-cli","tagline":"Using the Wonda CLI to generate images, videos, music, and audio from the terminal — plus LinkedIn, Reddit, and X/Twitter research and automation","description":"# Wonda CLI\n\nWonda CLI is a content creation toolkit for terminal-based agents. Use it to generate images, videos, music, and audio; edit and compose media; publish to social platforms; and research/automate across LinkedIn, Reddit, and X/Twitter.\n\n## Install\n\nIf `wonda` is not found on PATH, install it first:\n\n```bash\n# npm\nnpm i -g @degausai/wonda\n\n# Homebrew\nbrew tap degausai/tap && brew install wonda\n```\n\n## Setup\n\n- **Auth**: `wonda auth login` (opens browser, recommended) or set `WONDA_API_KEY` env var\n- **Verify**: `wonda auth check`\n\n### Organizations & spend context\n\nWondercat orgs are shared wallets with their own seats and billing.\nMembers can spend from the org wallet (instead of their personal credits)\nby switching context:\n\n- `wonda organizations list` (aliases: `wonda orgs list`, `wonda org list`) — see every org you belong to with your role and seat plan in each.\n- `wonda use --org ` — sticky org context for this machine. Sets\n `X-Wonda-Org` on every request; holds, charges, and `wonda balance`\n route through the org wallet.\n- `wonda use --personal` — back to personal.\n\n`wonda topup` always tops up your **personal** wallet, regardless of\ncontext. Topping up the org wallet (and configuring auto top-up) is\nadmin-only and happens on the web at `/organizations/`. If a\nmember runs out of org credits, the error tells them to ask an admin or\nswitch back to personal — they cannot top up the org wallet from CLI.\n\nRoles inside an org are separate from the seat plan:\n\n- **Owner**: the original creator. Cannot be demoted or kicked. Can transfer ownership to another member from the org page (rare).\n- **Admin**: can invite (single or bulk via paste), kick, change roles, change seats, top up, configure auto top-up, change monthly limits.\n- **User**: can only spend within the org wallet (subject to a per-member monthly limit if the admin set one).\n\nA paid org seat (`WONDA` / `WONDA_PREMIUM`) grants the same paid feature access (skills, etc.) as a personal paid plan, but only while in org context. `wonda use --personal` falls back to the user's personal account plan.\n\n### Access tiers\n\nNot all commands are available to every account type:\n\n| Tier | Access |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Anonymous** (temporary account, no login) | Media upload/download, editing (`video/edit`, `image/edit`, `audio/edit`), transcription, social publishing, scraping, analytics |\n| **Free** (logged in, Basic/Free plan) | Everything above + **generation** (`image/generate`, `video/generate`, etc.), styles, recipes, brand |\n| **Paid** (Plus, Pro, or Absolute plan) | Everything above + **video analysis** (requires credits), **skill commands** (`wonda skill install/list/get`) |\n| **Flagged** (per-account PostHog flags) | `wonda transitions` (transitionsEnabled), `wonda clipping` (clippingEnabled). Flip the flag in PostHog for the account. |\n| **Local** (no API call, no credits) | `wonda brand extract ` (no `--save`) extracts brand tokens from a URL via the bundled Patchright + Chromium driver. No auth required. Requires a one-time `wonda stealth-browser install` first. |\n\nIf a command returns a `403` error, check your plan at https://app.wondercat.ai/settings/billing.\n\n### Social signups (Instagram, TikTok, etc.)\n\nDrive them with the `wonda device` primitives + a throwaway mailbox from `wonda email`. The screenshot → decide → tap/type/swipe loop is how these flows work — there's no shortcut command, and that's fine: social apps change their UI constantly and any canned flow would drift faster than you could maintain it.\n\nStandard loop:\n\n1. `wonda email account create --random` → save `{email, password}`. Persist the resulting platform login with `wonda credentials create --website instagram.com --username --email --password-stdin <<< \"\"` (passwords are AES-256-GCM encrypted at rest; retrieve later with `wonda credentials get `).\n2. `wonda device create` → pick a `ready` device (poll `wonda device get --fields status`).\n3. `wonda device launch com.instagram.android` (or `com.zhiliaoapp.musically` for TikTok). Fall back to `wonda device open-url` if you'd rather start in the web flow.\n4. Loop: `wonda device screenshot > s.json` → decode the base64 PNG → read → pick an action → `tap | type | swipe | key` → screenshot again. Use `--text \"SomeButtonLabel\"` on `tap` before guessing coordinates; fall back to `--x --y` read off the screenshot for elements without matching text (number pickers, date spinners, etc.).\n5. When the app sends a verification email, `wonda email inbox wait --timeout 120` — returns `{codes: [\"483921\"], links: [...]}` with the 6-digit code already extracted. `wonda device type --text \"\"` to feed it back. **Race-safety**: capture a timestamp _before_ triggering the signup (`SINCE=$(date -u +%FT%TZ)`) and pass `--since \"$SINCE\"` — otherwise a fast mail server can land the email before your wait call and the old snapshot filters it out.\n6. For number/date spinners: tap on the highlighted cell, Android pops up a numeric or alphabetic keyboard, `wonda device type --text \"\"` replaces the selected text. `wonda device key --code 4` dismisses the keyboard when done.\n\n**Consent-like taps** — anything that accepts Terms/Privacy/Cookies, grants permissions, or publishes something. Before starting an automation that may hit these, ask the user once in chat whether to auto-accept them. If they say yes, tap through without pausing; if they say no, stop at each one and confirm. This does not apply to CAPTCHAs or \"prove you're human\" puzzles — always hand those off via `wonda device stream` (see next section).\n\n**Rate-limit signals** — if the app shows you a visual puzzle (\"we want to make sure you're a real person\"), stop and hand off to the user with `wonda device stream ` (see next section). Don't click through puzzles yourself.\n\n### Voice cloning\n\nClone a voice from a 10s+ audio clip and use it in TTS. Hard limit: 20 cloned voices per account. Cost: $1.50 per clone.\n\n```bash\n# Clone from a local file (auto-uploads to media library first)\nwonda voice create \"Andu\" --file ./sample.mp3 --description \"My voice\"\n\n# Clone from existing wonda media\nwonda voice create \"Brand\" --media-id \n\n# Optional source-audio preprocessing\nwonda voice create \"Clean\" --file ./raw.wav --noise-reduction --normalize-volume\n\n# List cloned voices (each row reports isExpired and expiresInDays)\nwonda voice list\n\n# One voice\nwonda voice get \n\n# Rename / re-describe (local only, no provider call)\nwonda voice update --name \"New Name\" --description \"...\"\n\n# Delete\nwonda voice delete \n```\n\n**Use a cloned voice in TTS** by passing the `providerVoiceId` from `voice get` as `voiceId` to `/audio/speech`:\n\n```bash\nwonda audio speech \"Hello world\" \\\n --model minimax-speech-2-8-hd \\\n --params '{\"voiceId\":\"\"}'\n```\n\n**7-day expiry**: cloned voices that haven't been used in TTS within 7 days are automatically expired. Running TTS with a cloned voice automatically refreshes its expiry. Idle voices that lapse must be re-cloned ($1.50 again).\n\n### Credentials vault\n\nPersist logins created on external platforms (Instagram, TikTok, Twitter, etc.) so they can be reused on the next run. Passwords are AES-256-GCM encrypted with a server-side key and only decrypted on `get`.\n\n```bash\n# Create\nwonda credentials create --website instagram.com --username myhandle \\\n --email me@example.com --password-stdin <<< \"hunter2\" \\\n --metadata '{\"signup_source\":\"wonda-email\"}'\n\n# List (passwords omitted)\nwonda credentials list --website instagram.com\n\n# Get full record including decrypted password\nwonda credentials get \n\n# Update any field (use --password-stdin to rotate; --username \"\" to clear)\nwonda credentials update --username newhandle\n\n# Delete\nwonda credentials delete \n\n# Fetch + record why you're using it in one call — POST, not GET, because\n# it writes a 'used' event with the reason. Prefer this over `get` whenever\n# you can articulate the reason.\nwonda credentials use --reason \"instagram signup flow\"\n\n# See recent events (created / used / rotated / updated) for audit\nwonda credentials events \n```\n\nFields: `website` (required — typed input like `insta` is canonicalized to `instagram.com`), `username`, `email`, `password` (required), `metadata` (arbitrary JSON). At least one of `username` / `email` must be present. Multiple records per `(website, username)` are allowed — dedupe on your side if you need to.\n\n**Event log**: every `credentials get`/`use`, `create`, password rotate, and other updates are recorded as events on the credential (actor: `cli` | `web` | `system`). Use `credentials events ` or the web UI's history icon to audit. The event log is append-only and cascades on credential delete.\n\n### Handing off to a human\n\nIf automation hits a screen that requires a human to take over (consent flow you shouldn't auto-accept, ambiguous UI, step where the user prefers to act themselves), use `wonda device stream ` — returns a `playerUrl` signed with a short-lived JWT (1h). Give that URL to the user, they act in their own browser, and automation can resume afterward.\n\n```bash\nwonda device stream \n# → { \"streamUrl\": \"wss://…\", \"playerUrl\": \"https://…\", \"deviceType\": \"social\" }\n```\n\n### Global output flags\n\nAll commands support these output control flags:\n\n- `--json` — Force JSON output (auto-enabled when stdout is piped)\n- `--quiet` — Only output the primary identifier (job ID, media ID, etc.) — ideal for scripting\n- `-o ` — Download output to file (implies `--wait`)\n- `--fields status,outputs` — Select specific JSON fields\n- `--jq '.outputs[0].media.url'` — Filter JSON output with a jq expression\n\n## How to think about content creation\n\nYou are a marketing director with access to a full production toolkit. Before touching any tool, think:\n\n1. **What product category?** (beauty, food, tech, fashion, fitness, etc.)\n2. **What format performs for this category?** (UGC memes for everyday products, cinematic for luxury, before/after for transformations, testimonial for services)\n3. **What's the hook?** (relatable scenario, surprising twist, aspirational lifestyle, social proof)\n4. **What specific scene?** (not \"product on table\" but \"person discovering the product in a funny situation\")\n\n## Decision flow\n\nWhen asked to create content, follow this order:\n\n### Step 1: Gather context\n\n```bash\nwonda brand # Active brand: identity, colors, fonts, logos, products\nwonda brand list # All brands owned by this account/org\nwonda brand show # Specific brand\nwonda brand extract https://stripe.com # Local-only: writes ./output/stripe.com/{DESIGN.md, tokens.json, assets/}\nwonda brand extract https://stripe.com --save --make-active # Local + persist + activate (the common path)\nwonda brand extract https://stripe.com --save --name \"Stripe\" # Persist with a custom name\nwonda brand extract https://stripe.com --no-output --save # Don't write to disk, persist only\nwonda brand save # Persist the most recent ./output// dir to the server\nwonda brand save --from ./output/stripe.com --make-active\nwonda brand pull # Download a saved brand back to ./output//\nwonda brand activate # Set as the active brand\nwonda brand upload-logo https://acme.com/logo.svg # Attach a logo by URL (--variant wordmark|icon|dark|light)\nwonda brand upload-font https://acme.com/Geist.woff2 --weight 700\nwonda brand delete \nwonda analytics instagram # What content performs well\nwonda scrape social --handle @competitor --platform instagram --wait # Competitive research (if relevant)\n\n# Cross-platform research (if relevant)\nwonda x search \"topic OR keyword\" # Find conversations on X/Twitter\nwonda x user-tweets @competitor # Competitor's recent tweets\nwonda reddit search \"topic\" --sort top --time week # Reddit discussions\nwonda reddit feed marketing --sort hot # Subreddit trends\nwonda linkedin search \"topic\" --type COMPANIES # LinkedIn company/people research\nwonda linkedin profile competitor-vanity-name # LinkedIn profile intel\n```\n\n### Step 2: Check content skills\n\nContent skills are step-by-step guides for common content types. Each skill tells you exactly which models, prompts, and editing operations to use — and in what order. ALWAYS check skills before building from scratch.\n\n```bash\nwonda skill list # Browse all content skills\nwonda skill get # Full step-by-step guide for a skill\n```\n\n**Full skill index:**\n\n| Slug | Description | Input |\n| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |\n| product-video | Product/scene video — prompt library for all categories | optional product image |\n| ugc-talking | Talking-head UGC — single clip, two-angle PIP, or 20s+ with B-roll | optional reference |\n| ugc-reaction-batch | Batch TikTok-native UGC reactions with viral strategy | optional product image |\n| tiktok-ugc-pipeline | Scrape viral reel → generate 5 UGC → post as drafts | reel or TikTok URL |\n| ugc-dance-motion | Dance/motion transfer | image + video |\n| marketing-brain | Marketing strategy brain — hooks, visuals, ads | user brief |\n| reddit-subreddit-intel | Scrape top posts, analyze virality, generate ideas | subreddit + product |\n| twitter-influencer-search | Find X influencers and amplifiers | competitor/niche keywords |\n| tiktok-slideshow-carousel | 3-slide TikTok carousel — hook, bridge, product reveal | app screenshot + audience |\n| creative-static-ads | Single-frame static ad images — 6 conversion pillars, 8 archetypes, 8 psychological hooks | product + optional image |\n| ffmpeg | All local ffmpeg recipes — trim, audio swap, captions, social formats, scene split, silence cut, frame extraction, analysis artifacts | local video path or mediaId |\n| image-edit | All image edit paths — img2img, background removal, crop, text overlay, vectorize | image mediaId or local path |\n\n**If a skill matches** → `wonda skill get `, read it, adapt to context, execute each step.\n\n**If no skill matches** → build from scratch (Step 3).\n\n### Step 2.5: Decide whether finishing should be local\n\nNot every media task should go back through Wonda editing. Use this routing rule:\n\n- Use `wonda` for AI generation, AI transcription/alignment, scraping, publishing, hosted transitions, and workflows that need media IDs or remote jobs.\n- Use local `ffmpeg` for deterministic transforms on files you already have or can download: trim, crop/scale/pad, concat (merging multiple clips), replace audio, extract audio/frame, reverse, normalize for delivery, burn captions, split scenes, cut silence, and build analysis artifacts. **Always merge clips locally** — server-side merge can hang for 30+ minutes once any input exceeds ~7MB.\n\nWhen a task starts from a Wonda media ID but the actual edit is deterministic, move it to local files first:\n\n```bash\nwonda media download -o ./input.mp4\n```\n\nBefore any local ffmpeg work:\n\n```bash\nwhich ffmpeg\nwhich ffprobe\nffmpeg -version\nffprobe -v error -show_format -show_streams -of json ./input.mp4\n```\n\nFont rule for local caption/text work:\n\n- Prefer an explicit font file path over a family name.\n- Never assume a font exists. Check first with `fc-match`, `fc-list`, `/System/Library/Fonts`, `/Library/Fonts`, `~/Library/Fonts`, or `/usr/share/fonts`.\n- If the task is mainly local finishing/captions/formatting/splitting/artifact extraction, check the `ffmpeg` skill before inventing commands.\n- `wonda edit video` renders locally for every single-video op (`trim`, `crop`, `speed`, `volume`, `textOverlay`, `animatedCaptions` with supplied captions, `editAudio`). No flag needed: the server returns a manifest, the CLI renders it, uploads the output, and finalizes the editor_job. Multi-video ops (`overlay`, `splitScreen`, `splitScenes`, `motionDesign`, `merge`) are not handled by `wonda edit video`. Build them locally with the `ffmpeg` skill instead (concat, overlay, hstack/vstack, scene assembly). **Never mix per-clip audio then concat** — concat the video tracks first, then layer the full voiceover or music track once over the joined timeline. Per-clip audio bakes create cut-line collisions and silent gaps.\n\nDefault local export target unless the user asked otherwise:\n\n```bash\n-c:v libx264 -preset medium -crf 18 -pix_fmt yuv420p -movflags +faststart -c:a aac -b:a 192k\n```\n\nAlways pass `-y` as the first flag so the command auto-overwrites the output. `ffmpeg` prompts interactively when the output path exists and agent shells hang on that prompt until timeout.\n\n### Step 3: Build from scratch (chain endpoints)\n\nWhen no skill matches, chain individual CLI commands. Each step produces an output that feeds into the next.\n\n**Single asset:**\n\n```bash\nwonda generate image --model gpt-image-2 --prompt \"...\" --aspect-ratio 9:16 --wait -o out.png\n# --params '{\"quality\":\"high\"}' — auto/low/medium/high (default auto)\n# --negative-prompt \"...\" — override what to exclude (model-dependent)\n# --seed — pin the seed for reproducible results (model-dependent)\nwonda generate video --model seedance-2 --prompt \"...\" --duration 5 --params '{\"quality\":\"high\"}' --wait -o out.mp4\nwonda generate text --model --prompt \"...\" --wait\nwonda generate music --model suno-music --prompt \"upbeat lo-fi\" --wait -o music.mp3\n```\n\n**Audio (speech, transcription, dialogue):**\n\n```bash\n# List available voices (TTS + dialogue use the same set)\nwonda audio voices\n\n# Text-to-speech\nwonda audio speech --model elevenlabs-tts --prompt \"Your script here\" \\\n --params '{\"voiceId\":\"hpp4J3VqNfWAUOO0d1Us\"}' --wait -o speech.mp3\n# elevenlabs-tts always requires a voiceId — pick one from `wonda audio voices`\n\n# Transcribe audio/video to text\nwonda audio transcribe --model elevenlabs-stt --attach $MEDIA --wait\n\n# Multi-speaker dialogue (each speaker needs a voiceId from `wonda audio voices`)\nwonda audio dialogue --model elevenlabs-dialogue \\\n --prompt 'ALICE: Hi! BOB: Hello!' \\\n --params '{\"speakers\":[{\"label\":\"ALICE\",\"voiceId\":\"hpp4J3VqNfWAUOO0d1Us\"},{\"label\":\"BOB\",\"voiceId\":\"IKne3meq5aSn9XLyUdCD\"}]}' \\\n --wait -o dialogue.mp3\n```\n\n**Audio AI operations (direct-inference, NOT editor ops):**\n\n```bash\n# Denoise / dereverberate speech\nwonda audio enhance --model replicate-resemble-enhance --attach $MEDIA \\\n --params '{\"denoise\":true,\"chunkSeconds\":10}' --wait -o enhanced.wav\n\n# Split a track into voice and instrumental stems\nwonda audio extract-voice --model replicate-demucs --attach $MEDIA \\\n --wait -o vocals.wav\n```\n\nDO NOT use `wonda edit video --operation enhanceAudio` or `--operation voiceExtractor` — those paths are deprecated. They still work but emit a warning, and they route through the heavier editor_job pipeline for no functional reason.\n\n**Add animated captions to a video:**\n\nThe `animatedCaptions` operation handles everything in one step — it extracts audio, transcribes for word-level timing, and renders animated word-by-word captions onto the video.\n\n```bash\n# Generate a video with speech audio\nVID_JOB=$(wonda generate video --model seedance-2 --prompt \"...\" --duration 5 --aspect-ratio 9:16 --params '{\"quality\":\"high\"}' --wait --quiet)\nVID_MEDIA=$(wonda jobs get inference $VID_JOB --jq '.outputs[0].media.mediaId')\n\n# Add animated captions (single step)\nwonda edit video --operation animatedCaptions --media $VID_MEDIA \\\n --params '{\"fontFamily\":\"TikTok Sans SemiCondensed\",\"position\":\"bottom-center\",\"sizePercent\":80,\"strokeWidth\":2.5,\"fontSizeScale\":0.8,\"highlightColor\":\"rgb(252, 61, 61)\"}' \\\n --wait -o final.mp4\n```\n\nThe video's original audio is preserved. Do NOT replace the audio with TTS — Sora already generated the speech.\n\n**Alternative engine: `--captions-engine ffmpeg`.**\n\nUse when the user wants the typewriter look or an opaque/rounded chyron behind the active word. Plain `brew install ffmpeg` is enough. This path is CLI-only today (it does not go through `editor_job`, so credits are not charged for the render).\n\n```bash\n# progressive (default for ffmpeg engine) — cumulative reveal,\n# optional rounded pill behind the active word via highlightColor.\nwonda edit video --operation animatedCaptions \\\n --captions-engine ffmpeg --captions-preset progressive \\\n --media $VID_MEDIA \\\n --caption-segments \"$(echo \"$STT_OUT\" | jq -c '.outputs[] | select(.outputKey==\"wordTimestamps\") | .outputValue | map({text: .word, startS: .start})')\" \\\n --params '{\"fontFamily\":\"TikTok Sans\",\"textColor\":\"#FFFFFF\",\"strokeColor\":\"#000000\",\"strokeWidth\":3,\"fontSizeScale\":1.1,\"paddingBottom\":25,\"highlightColor\":\"#FF3D3D\",\"backgroundBorderRadius\":18}' \\\n -o final.mp4\n\n# typewriter — letters appear one at a time at constant interval (60ms/char)\n# with a square white caret. Pass plain white text (no background).\nwonda edit video --operation animatedCaptions \\\n --captions-engine ffmpeg --captions-preset typewriter \\\n --media $VID_MEDIA \\\n --caption-segments \"$STT_WORD_TIMESTAMPS\" \\\n --params '{\"fontFamily\":\"TikTok Sans\",\"textColor\":\"#FFFFFF\",\"fontSizeScale\":1.1,\"paddingBottom\":12}' \\\n -o final.mp4\n```\n\nFonts are bundled into the binary, so the standard `fontFamily` values (TikTok Sans variants, Nohemi, Comic Cat, Gavency) work out of the box with no extra setup. `--fonts-dir` is an optional override for power users who want to bring their own font collection: when set, the renderer searches that directory first and only falls back to the bundled set if it doesn't find a match.\n\nVertical placement is controlled by `paddingBottom` (a percentage of canvas height, distance from canvas bottom to the caption's bottom edge). Sensible values: `12` for traditional bottom-of-frame subtitles, `25` for the TikTok 3/4-from-top sweet spot, `35` for visibly mid-bottom. `paddingTop` does the same when `position` starts with `top-*`. Without these, captions snap to the very edge of the canvas.\n\n**Transitions (effects pipelines on a single video):**\n\n```bash\nwonda transitions presets # List built-in presets (JSON)\nwonda transitions operations # Grouped by category (analysis/effect/...)\nwonda transitions operations --json # Full per-param metadata\nwonda transitions llms # Full reference (presets + ops + dependencies)\nwonda transitions run --media $VID --preset flash_glow --wait -o out.mp4\n# Or send an agent-generated timeline of clips (inline JSON):\nwonda transitions run --media $VID \\\n --clips '[{\"layer_type\":\"video\",\"start_frame\":0,\"end_frame\":60}]' --wait -o out.mp4\n# Or from a file (handy for long agent timelines):\nwonda transitions run --media $VID --clips ./timeline.json --wait -o out.mp4\n# To attach scene_transitions: pass an envelope (clips + scene_transitions)\n# instead of a bare clip array — same file, both fields forwarded.\nwonda transitions run --media $VID --clips ./timeline_with_transitions.json --wait -o out.mp4\n# where timeline_with_transitions.json is:\n# { \"clips\": [...],\n# \"scene_transitions\": [{\"name\":\"crossfade\",\"params\":{\"duration\":8},\"boundaries\":[60]}] }\nwonda transitions job # Poll a transition job\n```\n\nUse exactly one of `--preset` or `--clips`. Requires a full (logged-in) account. **Always read `wonda transitions llms` first when composing a clips timeline.** It documents the detect/segment/effect dependencies, which ops need masks, and the full clip-spec shape (layer types, tracks, effects, transforms).\n\n**Preset variables (`variables` block).** Each preset declares the template variables it accepts under `variables` in `wonda transitions presets`. Each entry has `name`, `description`, and `required`. Required variables MUST be supplied or the job is rejected with a 400 — no more silent skipping. Pass them with `--var name=value` (repeatable) or, for the common `prompt` case, the `--prompt` shortcut:\n\n```bash\n# flash_glow_prompted requires { prompt }\nwonda transitions run --media $VID --preset flash_glow_prompted \\\n --prompt \"woman in white dress\" --wait -o out.mp4\n\n# text_behind_person requires { prompt, text }\nwonda transitions run --media $VID --preset text_behind_person \\\n --var prompt=\"the person\" --var text=\"HELLO WORLD\" --wait -o out.mp4\n\n# Numeric-typed vars: bare digits are decoded as numbers, \"true\"/\"false\" as\n# bools, everything else stays a string. Presets that compare frame indices\n# numerically (border_frame, marquee_text, quick_motion_text, bg_remove_scale)\n# need this — quoting an int turns it back into a string.\nwonda transitions run --media $VID --preset border_frame \\\n --var exit_start_frame=200 --var exit_end_frame=251 --wait -o out.mp4\n```\n\nThe `prompt` variable is a **detection text query** describing which subject to mask, fed to SAM3 to produce per-frame segmentation masks. Not a content-generation prompt.\n\nBuilding a custom `--clips` timeline that needs detection masks? Add a clip with `layer_type: \"video\"` and a `mask: {layer_type: \"mask\", analysis_steps: [{name: segment, params: {prompt: \"...\"}}]}`. SAM3 handles both detection and segmentation in one step from the prompt, so no separate `detect` step is needed.\n\n### Pre-warming masks before render (recommended)\n\nFor presets with `mask: