# Ralphy CLI Surface (generated)

> DO NOT EDIT. Regenerate via `bun run cli:surface:build`.
> The hand-curated companion lives at `docs/cli-surface.md`.

Verbs registered: **43**

## Top-level verbs

### `ralphy version`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy version [options]

Print the ralphy version (same as -v / --version)

Options:
  -h, --help  display help for command
```

### `ralphy new`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy new [options] [brief...]

Create a new project under <workspace>/projects/<id>/ with a canonical layout.
Lightweight on-ramp — pass a brief to seed BRIEF.md or just --id <slug> for an
empty shell. Equivalent to `ralphy project create` but with positional brief +
auto-defaulted --name (issue #031).

Arguments:
  brief                   Brief — free-form text describing the video to make

Options:
  --id <slug>             Project id slug (default: derived from brief or
                          YYMMDD-HHMMSS)
  --name <name>           Display name (default: title-cased id)
  --brand <id>            Brand id (registry lookup)
  --persona <id>          Persona id (registry lookup)
  --template <id>         Template id
  --platform <platform>   Target platform (default: "tiktok")
  --aspect-ratio <ratio>  Aspect ratio (default: "9:16")
  --duration <seconds>    Target duration in seconds
  -h, --help              display help for command

Examples:
  ralphy new "Spring 2026 ad for Acme dental floss"
  ralphy new --id summer-launch-001
  ralphy new "office-set walkthrough" --id office-walk-001
```

### `ralphy clone`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy clone [options] <url-or-ref>

Lift the style of a public clip into a reusable vibe-style template. Chains ref
pull → frames → analyze → blueprint → template create.

Arguments:
  url-or-ref            Public source URL (TikTok / Reels / Shorts / X) OR a
                        registered ref slug

Options:
  --as-template <id>    Output template id (default: derived from source slug)
  --strict-look         Mirror palette + grading + hook in the blueprint
  --prompt-only         Skip music / voice extraction (faster; visual prompts
                        only)
  --analyze-model <id>  Vision model id for frame analysis (default
                        google/gemini-2.5-flash)
  -h, --help            display help for command

Examples:
  ralphy clone https://tiktok.com/@x/video/72939...
  ralphy clone https://www.instagram.com/reel/Cabc123 --as-template winter-vibe-002
  ralphy clone existing-ref-slug --strict-look --prompt-only
```

### `ralphy skill`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy skill [options] [command]

Manage Ralphy skill installs across AI agents

Options:
  -h, --help            display help for command

Commands:
  install [options]     Install the Ralphy skill bundle into the selected agent
                        (claude / cursor / codex)
  uninstall [options]   Remove the Ralphy skill bundle + sentinel block from the
                        selected agent
  new [options] <name>  Scaffold a new skill: .agents/skills/<name>/SKILL.md +
                        docs/playbooks/<name>.md
  help [command]        display help for command

Examples:
  ralphy skill install --agent claude
  ralphy skill install <pack>      # alias: pass --agent <pack> through to the installer
  ralphy skill uninstall --agent claude
```

### `ralphy setup`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy setup [options]

Setup wizard — API keys, dev services

Options:
  --status                Print capability status as JSON and exit (no TUI)
  --link <path>           Link ralphy to a project directory (global config)
  --unlink                Remove the global project link
  --non-interactive       Agent / CI mode: never prompt, never open a TUI, emit
                          a JSON summary (default: false)
  -y, --yes               Alias for --non-interactive (default: false)
  --openrouter-key <key>  Set OPENROUTER_API_KEY (use `-` to read from stdin).
                          Implies --non-interactive
  --elevenlabs-key <key>  Set ELEVENLABS_API_KEY (use `-` to read from stdin).
                          Implies --non-interactive
  --keys-from-env         Pick up OPENROUTER_API_KEY / ELEVENLABS_API_KEY from
                          the current process env. Implies --non-interactive
                          (default: false)
  --project-dir <path>    Link ralphy to this project directory before
                          configuring keys. Implies --non-interactive
  --no-verify             Skip API ping verification when saving keys
  --allow-unverified      When --verify is on (default) and a key fails to
                          verify, save it anyway and exit 0 (default: false)
  -h, --help              display help for command
```

### `ralphy status`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy status [options]

Show enabled capabilities + linked project

Options:
  -h, --help  display help for command
```

### `ralphy doctor`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy doctor [options]

Env health check — keys, dependencies, project link. JSON for scripts; -p for
human view.

Options:
  -h, --help  display help for command
```

### `ralphy generate`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy generate [options] [command]

Generate a single asset (image / video / voiceover / music / captions). Logs
cost + path automatically.

Options:
  -h, --help             display help for command

Commands:
  image [options]        Generate one image via OpenRouter (default:
                         google/gemini-3-pro-image-preview — nano-banana-pro,
                         multi-ref consistency, ≥4 concurrent). Pass --model
                         openai/gpt-5.4-image-2 when label typography matters
                         more than ref consistency.
  image-batch [options]  Fan out N image gens from a directory of `*.txt` prompt
                         files (each file → one slot named by stem). Shares
                         --model / --ref / --size across the batch; respects
                         #007 per-endpoint concurrency. #024
  video [options]        Generate one video via OpenRouter (default:
                         kling-v3.0-pro)
  voiceover [options]    Generate voiceover via ElevenLabs (default:
                         eleven_multilingual_v2)
  music [options]        Generate music bed via ElevenLabs Music (instrumental
                         by default)
  sfx [options]          Generate a sound effect via ElevenLabs Sound Generation
                         (≤22s)
  captions [options]     Transcribe audio to Caption[] (≤25MB). Default backend:
                         ElevenLabs Scribe v1 (word-level).
  help [command]         display help for command
```

### `ralphy provider`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy provider [options] [command]

Inspect provider connectors and their capability matrix (image / video / voice /
music / sfx / text / transcribe).

Options:
  -h, --help      display help for command

Commands:
  list            List registered provider connectors, their capabilities, and
                  whether each is configured (key present).
  help [command]  display help for command
```

### `ralphy models`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy models [options] [command]

Inspect available OpenRouter video models and their per-model parameter
constraints

Options:
  -h, --help           display help for command

Commands:
  list [options]       List all OR video-generation models with their per-model
                       durations / resolutions / aspect-ratios / frame-anchor
                       support
  show [options] <id>  Show full per-model schema (description + params + price
                       estimate) for one model
  alias [shorthand]    Resolve a model shorthand (`kling`, `nano banana pro`,
                       `gpt image 2`, ...) to its canonical OpenRouter slug.
                       With no argument, prints the full alias map.
  help [command]       display help for command
```

### `ralphy daemon`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy daemon [options] [command]

Manage the local job worker (background process that executes queued ralphy
jobs)

Options:
  -h, --help       display help for command

Commands:
  start [options]  Start the daemon as a detached background process
  stop             Send SIGTERM to the daemon and wait up to 7s for graceful
                   exit
  status           Report whether the daemon is running and how many jobs are in
                   each state. Exits 2 if pending jobs exist but no worker is
                   running.
  help [command]   display help for command
```

### `ralphy queue`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy queue [options] [command]

Manage the local job queue (add work, watch progress, cancel, retry)

Options:
  --auto-start             Spawn the daemon if it's not running before applying
                           the subcommand (default off) (default: false)
  -h, --help               display help for command

Commands:
  add [options] <argv...>  Enqueue a raw shell command as a job. Pass the
                           wrapped command after `--`. For ralphy generate jobs,
                           use `generate ... --queue` instead.
  list [options]           List jobs (default: most recent first, all states)
  show <id>                Show full details of one job
  cancel [options] [id]    Cancel a pending/running job by id, OR bulk-cancel by
                           --tag and/or --state. Status is flipped to
                           'cancelled' (rows are never deleted).
  retry [options] [id]     Re-queue a failed/cancelled/blocked job by id, OR
                           bulk-retry by --tag and/or --state. Resets status to
                           'pending' and bumps retry_count (logs are preserved).
  logs [options] <id>      Print all captured stdout+stderr lines for one job
  watch [options] [id]     Live monitor: with <id>, tails one job's logs in real
                           time; without, renders an ANSI dashboard of all
                           active jobs (Ctrl-C to exit)
  help [command]           display help for command
```

### `ralphy render`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy render [options] <project>

Render a project to MP4. Engine: HyperFrames (HTML + GSAP). Writes
<project>/render/final.mp4. Adds EBU R128 loudnorm with --loudnorm. Also
auto-emits a compressed social sibling render/final-social.mp4 (CRF 20 default,
x264 faststart) so 'render → upload' is one command; pass --no-compress to skip
it.

Arguments:
  project                Project ID

Options:
  --composition <id>     Composition id (default: index.html)
  --output <path>        Output mp4 path (default: <project>/render/final.mp4)
  --from-clip <path>     Pure-clip deliverable mode: faststart-wrap (and
                         optionally loudnorm) an existing mp4 instead of running
                         the HyperFrames engine. Logs to the project's gen-log
                         so the single-entry-point invariant (AGENTS.md #2)
                         holds. #009
  --loudnorm             Apply EBU R128 loudnorm (-16 LUFS) post-render via
                         ffmpeg
  --fps <fps>            Frame rate (default 30)
  --quality <quality>    Quality preset: draft|standard|high (HyperFrames
                         engine) OR web|print|archive (post-render CRF 23|18|12)
  --grade <preset>       Color-grade preset post-render: tv-commercial-soft |
                         tv-commercial-strong | cinematic-teal-orange |
                         analog-horror
  --format <format>      Output format: mp4|webm|mov|png-sequence (default mp4)
  --resolution <preset>  Resolution preset:
                         portrait|landscape|square|1080p|4k|...
  --music-variants       After the base render, mix one variant per
                         <project>/artifacts/music/*.mp3 onto the final mp4.
                         Writes render/final.<music-basename>.mp4 per bed. #049
                         (default: false)
  --music-volume <n>     Music gain for --music-variants (default 0.18,
                         background bed under VO) (default: 0.18)
  --no-compress          Skip the auto social-compressed deliverable
                         (render/final-social.mp4)
  --social-crf <n>       x264 CRF for the auto social cut (default 20; raise for
                         smaller files, lower for cleaner grain) (default: 20)
  --workers <n>          Parallel capture workers (number or 'auto'). Lower to 1
                         for heavy compositions (many embedded videos / large
                         GSAP timelines) that hit 'Runtime.callFunctionOn timed
                         out' under the default auto fan-out.
  --dry-run              Print the resolved render plan; no engine run (default:
                         false)
  --summary              Collapse the dry-run plan to a per-stage rollup
                         (default: false)
  -h, --help             display help for command

Examples:
  ralphy render spring-001
  ralphy render proj-001 --loudnorm
  ralphy render proj-001 --output ./out.mp4
  ralphy render proj-001 --fps 60 --quality high
  ralphy render arena-rocker-001 --from-clip raw.mp4 --loudnorm
  ralphy render proj-001 --no-compress              # master only, skip final-social.mp4
  ralphy render proj-001 --social-crf 18            # higher-quality (larger) social cut

The social cut: every render also writes render/final-social.mp4 — an x264
faststart re-encode of the finalized master, sized for direct upload. Default
CRF is 20 (not 23) because grainy registers (PS1 / VHS) are high-entropy and
ring at higher CRFs; raise --social-crf for a smaller file at the cost of grain
fidelity, lower it for a larger, cleaner cut. The social cut inherits the
master's already-loudnormed audio (no double loudnorm) and never overwrites
render/final.mp4 (append-only).
```

### `ralphy hyperframes`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy hyperframes|hf [options] [command]

HyperFrames inner-loop verbs (lint / validate / snapshot / render / save-version
/ extract-frames / watch). Wraps `bunx hyperframes` so iterations log to
generations.jsonl. Issue #028.

Options:
  -h, --help                          display help for command

Commands:
  lint [options] <project>            Run the in-repo HyperFrames lint (issue
                                      #047). Exit 1 on errors, 0 on warnings
                                      only.
  validate <project>                  Run `bunx hyperframes validate` against
                                      the project and log the result.
  snapshot [options] <project>        Capture key-frame PNGs via `bunx
                                      hyperframes snapshot`. When --at is
                                      omitted, auto-picks one timestamp per
                                      scene from STORYBOARD.md / scenario.json.
  render [options] <project>          Render a project to MP4. Thin namespace
                                      wrapper over `ralphy render` that adds the
                                      --require-snapshot-review staleness gate
                                      and a hyperframes.render gen-log row.
  save-version <project>              Copy current index.html →
                                      compositions/v<N>.html (numeric increment,
                                      never overwrites). Closes invariant #14
                                      gap for HTML (issue #004).
  extract-frames [options] <project>  Extract still frames from a
                                      rendered/source video for QA via ffmpeg.
                                      Standalone helper — issue #012 may later
                                      route through a broader `ralphy video
                                      frame` verb.
  watch <project>                     Live-preview the composition via `bunx
                                      hyperframes watch`. Runs foreground;
                                      Ctrl-C to stop.
  help [command]                      display help for command

Examples:
  ralphy hyperframes lint spring-001
  ralphy hyperframes validate spring-001
  ralphy hyperframes snapshot spring-001                # auto --at from STORYBOARD
  ralphy hyperframes snapshot spring-001 --at 0.5 1.8 3.2
  ralphy hyperframes save-version spring-001            # → compositions/v1.html
  ralphy hyperframes render spring-001 --require-snapshot-review
  ralphy hyperframes extract-frames spring-001 --in render/final.mp4 --at 1.0 5.0
  ralphy hyperframes watch spring-001
```

### `ralphy editor`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy editor [options] [command]

Editor-stage observability — preflight clip checks, trim-analysis, composition
QA.

Options:
  -h, --help                          display help for command

Commands:
  preflight [options] <projectId>     ffprobe every clip + music in
                                      <project>/artifacts/, surface durations /
                                      fps / codec / audio / aspect, run a
                                      music-gap check, and verify every scenario
                                      scene has a corresponding clip on disk.
                                      Exit 1 on red. Run BEFORE `ralphy render`.
  trim-analyze [options] <projectId>  Run gemini-3.1-pro-preview vision over
                                      every clip in artifacts/videos/, write
                                      per-clip JSON to
                                      artifacts/analysis/<clip>.json, and
                                      aggregate to
                                      artifacts/analysis/summary.json.
                                      Idempotent: clips with mtime <= prior
                                      summary row are skipped. Parallelism is
                                      capped (default 3) to respect the
                                      gemini-3.1-pro-preview concurrency floor.
  help [command]                      display help for command
```

### `ralphy compose`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy compose [options] <projectId>

Timeline-aware composer. Reads artifacts/ + scenario.json + scribe captions,
builds a Timeline, optionally re-flows after structural edits, and renders a
single mp4. Replaces the hand-rolled concat+VO+music+loudnorm ffmpeg cycle
(#013).

Arguments:
  projectId                Project id (resolved via the registry to
                           .ralphy/workspaces/<ws>/projects/<id>/)

Options:
  --remove-segment <slot>  Drop the segment with this slot id and re-flow VO +
                           captions + music. Repeatable.
  --out <path>             Output path (default: <project>/render/compose.mp4).
                           Collisions auto-bump to -v2, -v3, ...
  --dry-run                Print the resolved timeline + filter graph; do not
                           spawn ffmpeg.
  -h, --help               display help for command
```

### `ralphy voice`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy voice [options] [command]

ElevenLabs voice library inspection — pre-flight checks before VO batches.

Options:
  -h, --help        display help for command

Commands:
  exists <voiceId>  Pre-flight check that an ElevenLabs voice ID resolves.
                    Returns 200 + voice metadata if OK, exits 1 with a clear
                    error if 404. Run before any multi-clip VO batch.
  clone [options]   Clone a voice into your ElevenLabs library via Instant Voice
                    Cloning (/v1/voices/add). Optional pre-pass through
                    /v1/audio-isolation strips background music / noise (#030).
  list              List voices available on the user's ElevenLabs account
                    (custom clones + favorites).
  help [command]    display help for command
```

### `ralphy whoami`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy whoami [options]

Show the per-user profile (skill score 0-10, developer badge, signals,
recommendation for adaptive intake). On first call, auto-backfills from on-disk
projects.

Options:
  --backfill         Scan every workspace (.ralphy/workspaces/*/projects/*) and
                     recompute signals from on-disk state (renders, postmortems)
                     (default: false)
  --set-level <n>    Pin skill score to <n> (0-10). Overrides auto-assessment.
  --set-developer    Mark this user as a developer — unlocks raw CLI suggestions
                     + ship-fast default (default: false)
  --unset-developer  Remove the developer badge (default: false)
  --reset            Reset profile to defaults (preserves firstSeen) (default:
                     false)
  --bump-session     Increment sessions_count (called by ralphy index on first
                     invocation per day) (default: false)
  -h, --help         display help for command
```

### `ralphy init`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy init [options]

Initialize workspace and config

Options:
  --defaults  Use all defaults without prompts
  -h, --help  display help for command
```

### `ralphy config`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy config [options] [command]

Manage configuration

Options:
  -h, --help         display help for command

Commands:
  list               Show all settings
  get <key>          Get a config value
  set <key> <value>  Set a config value
  help [command]     display help for command
```

### `ralphy brand`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy brand [options] [command]

Manage brands (design systems)

Options:
  -h, --help             display help for command

Commands:
  create [options]       Create a new brand
  list                   List all brands
  show <id>              Show brand details
  update [options] <id>  Update a brand
  delete <id>            Delete a brand
  extract <svg>          Parse an SVG and report layer structure: compound
                         paths, fill-rule, interior polygons, overlay rects.
                         JSON output.
  help [command]         display help for command
```

### `ralphy persona`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy persona [options] [command]

Manage personas (voice + style)

Options:
  -h, --help             display help for command

Commands:
  create [options]       Create a new persona
  list                   List all personas
  show <id>              Show persona details
  update [options] <id>  Update a persona
  delete <id>            Delete a persona
  help [command]         display help for command
```

### `ralphy ref`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy ref [options] [command]

Manage references (websites, social media)

Options:
  -h, --help                                     display help for command

Commands:
  add [options] <url>                            Add a reference URL to the registry
  create [options] <url>                         Alias of `ref add` — preferred form in playbooks
  list [options]                                 List all references
  show <id>                                      Show reference details
  attach [options] <refId>                       Attach reference to a project
  pull [options] [urls...]                       Pull a video via yt-dlp (single URL, default), OR bulk-download images when --kind reference-image / --from-file is set (#048). Bulk mode dedupes by sha256 and writes into <project>/artifacts/refs/.
  pull-site [options] <url>                      Fan-out Playwright crawl of a brand site → screenshots + tokens.json + apis.md (AGENTS invariant #15). Run BEFORE drafting brand-DNA or any code-on-screen creative.
  frames [options] <slug>                        Sample JPEG frames from <slug>/source.mp4 → <slug>/frames/
  transcribe [options] <slug>                    Transcribe <slug>/source.mp3 → <slug>/transcript.json (Caption[]). Default backend: ElevenLabs Scribe v1.
  analyze [options] <slug>                       Run vision LLM over <slug>/frames/* → <slug>/analysis.json. Default prompt = UGC blueprint extractor.
  analyze-video [options] <slug-or-path-or-url>  Send the full mp4 to Gemini for precise shot-cut detection (better than `analyze` for fast-cut commercials). Arg can be a ref slug, a local file path, or an http(s) URL.
  audio-describe [options] <slug>                Send <slug>/source.mp3 to Gemini-audio → <slug>/audio-analysis.json (tone, music, VO style)
  blueprint <slug>                               Synthesize <slug>/blueprint.md from {meta + analysis + audio-analysis + transcript}
  rasterize [options] <file>                     Rasterize a vector reference (SVG) to a crisp PNG at the requested long-edge size. Preserves intrinsic aspect ratio. `--bg <hex>` adds a solid background (default: transparent).
  paths <slug>                                   Print every research path for <slug> (helpful when scripting follow-ups)
  scrape-trends [options]                        Scrape TikTok hashtag pages via Playwright (Apify-compatible JSON shape) and rank with scoreTikTok()
  check [options] <project-id>                   Run the reference-required gate classifier on <project-id>'s scenario.json. Reports whether a real-entity name (person / brand-product / IP) was detected and, if so, whether at least one ref is attached. Exit 5 (gate) when the gate fires AND no ref is attached.
  delete <id>                                    Delete a reference
  locate [options]                               Locate an object in an image — returns pixel bbox(es) via Gemini vision
  help [command]                                 display help for command

Examples:
  ralphy ref pull https://tiktok.com/@x/video/72939...
  ralphy ref pull https://a.com/x.png https://b.com/y.jpg --kind reference-image --project my-proj-001
  ralphy ref pull --from-file urls.txt --kind reference-image --project my-proj-001
  ralphy ref pull-site https://example.com --project my-proj-001
  ralphy ref analyze my-reference-slug
  ralphy ref blueprint my-reference-slug
  ralphy ref check my-project-001                  # gate classifier on scenario.json
  ralphy ref check --text "Old Spice style hero"   # gate classifier on a raw brief
  ralphy ref locate --image shot.jpg --object "label tab on the bottle" --top-k 3
```

### `ralphy project`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy project [options] [command]

Manage video projects

Options:
  -h, --help                    display help for command

Commands:
  create [options]              Create a new project
  list [options]                List all projects
  show [options] <id>           Show project details
  update [options] <id>         Update project
  delete [options] <id>         Delete a project
  log [options] <id>            Tail project logs (generations / user-prompts /
                                user-assets)
  timeline <id>                 Merged project timeline (user requests + assets
                                + generations) as pretty chronological log
  log-prompt [options] [id]     Append a user-prompt entry to project logs.
                                Accept project id positionally OR via --project
                                (#031).
  log-asset [options] [id]      Append a user-asset entry to project logs.
                                Accept project id positionally OR via --project
                                (#031). With --copy-from <src>, copies the file
                                into <project>/artifacts/refs/ first
                                (auto-detects disposable macOS NSIRD / /tmp
                                paths and rescues them before they evaporate).
                                Sanitizes U+202F NARROW NO-BREAK SPACE in
                                filenames.
  score [options] <id>          Run virality rubric over scenario.json (Hard
                                fails + warnings, no LLM)
  transcribe [options] <id>     Transcribe an audio file → captions.json
                                (Caption[]). Default backend: ElevenLabs Scribe
                                v1 (word-level).
  clone [options] <id>          Clone a project
  move <id> <workspace>         Move a project into another workspace's
                                projects/ and update its registry entry.
                                Precondition: no background job (ralphy generate
                                / render) may be mid-flight on the project — its
                                file paths go stale on move.
  assets [options] <id>         ffprobe-truth every media file under
                                <project>/artifacts/ and emit a flat array.
                                Honors --kind video|image|audio.
  verify [options] <id>         ffprobe every slot in asset-manifest.json and
                                flag divergences from claimed duration /
                                dimensions / size (tolerance: 100ms on
                                duration). Exit non-zero on any red.
  thumbnail [options] <id>      Extract a single frame from a project video.
                                Default source: <project>/render/final.mp4.
  audio-stats [options] <id>    Loudness table (mean/peak dBFS + integrated LUFS
                                + true peak + LRA) for every audio file under
                                <project>/artifacts/.
  contact-sheet [options] <id>  Grid montage of images. --slots accepts a glob
                                over <project>/artifacts/images/ (e.g.
                                'zine-*'). Default cols=5.
  zip [options] <id>            Zip a project's deliverables into
                                <cwd>/<id>.zip. --selected = <project>/selected/
                                only. --all = everything except logs/cache.
  help [command]                display help for command
```

### `ralphy unit`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy unit [options] [command]

Manage project-local curated deliverables (units = copies of selected assets +
provenance)

Options:
  -h, --help                      display help for command

Commands:
  create [options] <project>      Form a unit by copying matched assets into
                                  units/<slug>/ + writing unit.json
  list <project>                  List units in a project
  show <project> <slug>           Show a unit's manifest + resolved media paths
  add [options] <project> <slug>  Copy more media into an existing unit (appends
                                  to media, never drops existing)
  delete <project> <slug>         Delete a unit directory (destructive — only
                                  run on explicit user intent)
  help [command]                  display help for command
```

### `ralphy blueprint`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy blueprint [options] [command]

Assemble / inspect a reproduction-grade Blueprint for a project's unit
(#074/#076)

Options:
  -h, --help                  display help for command

Commands:
  create [options] <project>  Capture a self-contained Blueprint for a unit into
                              units/<slug>/blueprint/ (append-only)
  list <project>              List units that have a captured blueprint/ + which
                              versions exist
  show [options] <project>    Print a unit's latest blueprint.json
  use [options] <unit-id>     Scaffold a ready-to-run project from a PUBLISHED
                              Blueprint (offline; #079)
  help [command]              display help for command

Examples:
  ralphy blueprint create choose-silenthill-001 --unit choose-silenthill
  ralphy blueprint list choose-silenthill-001
  ralphy blueprint show choose-silenthill-001 --unit choose-silenthill
  ralphy blueprint use choose-silenthill --project choose-silenthill-repro-001
```

### `ralphy library`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy library [options] [command]

Read the public content library (units, blocks, blueprints, formats) from the
static library.json on Bunny CDN (read-only)

Options:
  -h, --help      display help for command

Commands:
  units           Finished deliverables (Units)
  templates       Reusable template blocks
  recipes         Reusable recipe blocks
  assets          Reusable asset blocks
  blueprints      Per-unit reproduction blueprints
  formats         The media-format taxonomy (static)
  help [command]  display help for command

Examples:
  ralphy library units list
  ralphy library units show animated-fb-ad
  ralphy library templates list
  ralphy library recipes show noir-grade
  ralphy library blueprints list
  ralphy library blueprints show choose-magicschool
  ralphy library formats list

Source: static library.json on Bunny CDN (override the URL with RALPHY_LIBRARY_URL).
```

### `ralphy template`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy template [options] [command]

Manage scenario/video templates

Options:
  -h, --help                        display help for command

Commands:
  clone [options] <url-or-ref>      Lift the style of a public clip into a
                                    reusable vibe-style template. Chains ref
                                    pull → frames → analyze → blueprint →
                                    template create.
  create [options]                  Create a template (flat JSON) from a project
                                    or file
  register <id>                     Register an existing workspace dir template
                                    in the local registry
  list [options]                    List all templates (public library templates
                                    + the active workspace's templates/)
  show [options] <id>               Show template — prints TEMPLATE.md (the
                                    prompt-cookbook) for dir templates, JSON for
                                    flat. `--meta` prints the structured
                                    manifest facets (#075) for dir templates.
  use [options] <id>                Create a new project scaffolded from a
                                    template
  extract [options] <project-id>    Promote a finished workspace project into a
                                    reusable user-local template at the active
                                    workspace's templates/<slug>/
                                    (.ralphy/workspaces/<ws>/templates/). Copies
                                    prompts/, scenario, composition variables,
                                    and refs; substitutes brand/persona/VO with
                                    {{slots}}; drafts a README from POSTMORTEM
                                    'Lessons learned'. To publish it to the
                                    public library, use the templater /
                                    dev-publish-template path.
  delete <id>                       Delete a workspace template (flat file or
                                    whole dir). Public library templates are
                                    read-only — they live in the published
                                    library.json (Bunny CDN), not on disk.
  suggest [options] <utterance...>  Rank templates for a user utterance. Hybrid:
                                    substring scorer first (fast, free); if
                                    top-1 score is below threshold (default
                                    0.7), fall through to an LLM-rerank pass
                                    that handles Russian / paraphrase /
                                    concept-level / typo queries. Returns top-N
                                    with reasoning when LLM fires.
  help [command]                    display help for command

Examples:
  ralphy template suggest "unboxing video for my skincare brand"
  ralphy template list --format video
  ralphy template use <slug> --project <id> --brief "<the swap>"
```

### `ralphy guideline`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy guideline [options] [command]

Prompt-library guidelines — LLM rules for writing model-specific prompts

Options:
  -h, --help             display help for command

Commands:
  list                   List every guideline shipped in the repo
  show [options] <slug>  Print guideline.md raw (pipe-friendly for LLM
                         consumers)
  use [options] <slug>   Resolve a guideline tag — prints the body + the agent
                         tag for the next prompt
  help [command]         display help for command
```

### `ralphy memory`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy memory [options] [command]

Tiered memory store — global .ralphy/memory/ + per-workspace memory/ (markdown
entries, append-only)

Options:
  -h, --help                      display help for command

Commands:
  note [options] <text>           Write an ACTIVE memory entry directly (an
                                  explicit user remark is its own consent)
  propose [options] <text>        Stage a candidate entry into proposed/
                                  (promoted via `ralphy memory approve`)
  list [options]                  List memory entries (default: active entries
                                  of BOTH tiers)
  show [options] <slug>           Print one entry (no tier flag: workspace tier
                                  first, then global)
  search [options] <query>        Case-insensitive substring scan over
                                  frontmatter + body across both tiers
  approve [options] [slug]        Promote a proposed/ entry to active (+ index
                                  line). MOVE, never copy-and-delete
  reject [options] <slug>         Move a proposed/ entry to rejected/ (MOVE —
                                  the file is never unlinked)
  retire [options] <slug>         Move an ACTIVE entry (all its versions) to
                                  archived/ and drop its index line. MOVE, never
                                  delete
  curate [options]                LLM health pass over active entries: stage
                                  overlap-merges into proposed/, flag missing
                                  negative scope + stale references. Never
                                  mutates active entries
  distill [options] <project-id>  Distill a project's postmortem (02-lessons.md,
                                  05-workflow-fixes.md) into memory PROPOSALS —
                                  review with `ralphy memory approve`
  recall [options]                Merged digest for intake context: global +
                                  workspace active entries (workspace wins on
                                  slug collision)
  help [command]                  display help for command

Layout:
  global tier     .ralphy/memory/                    cross-workspace lessons (model quirks, craft, tooling)
  workspace tier  .ralphy/workspaces/<ws>/memory/    client / universe facts (cast, style DNA, rejections)
  per tier        <slug>.md + MEMORY.md index + proposed/ staging + rejected/

Append-only: re-noting an existing slug writes <slug>.v2.md (then v3...) and the
index points at the newest version; pass --force-overwrite for in-place replace.
Current dirs: /Users/maximovchinnikov/github/ugc-cli/.ralphy/memory
```

### `ralphy batch`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy batch [options] [command]

Manage batch operations

Options:
  -h, --help             display help for command

Commands:
  create [options]       Create a batch
  list                   List all batches
  show <id>              Show batch details
  status <id>            Show batch status
  delete [options] <id>  Delete a batch
  submit [options]       Submit a batch of jobs to the local daemon with
                         symbolic dependencies. Use this for the 'N generations
                         + 1 render' pattern.
  vary [options]         Create N project variants from a base project differing
                         on one axis (hook / body / cta / persona). Use this for
                         A/B testing the hook without re-running the rest of the
                         pipeline.
  help [command]         display help for command
```

### `ralphy asset`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy asset [options] [command]

Manage and generate assets

Options:
  -h, --help                 display help for command

Commands:
  list [options]             List assets in a project
  clean [options]            Remove assets from a project
  chromakey [options] <img>  Key out a background colour from a single image →
                             transparent PNG. Uses ffmpeg `colorkey`. Default
                             colour is 0x00b140 (greenscreen green); pass
                             `--despill` for a `colorhold` cleanup pass that
                             kills the green halo on anti-aliased edges.
  help [command]             display help for command
```

### `ralphy workspace`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy workspace [options] [command]

Manage workspaces (studio / universe groupings of projects with a shared/ asset
tier)

Options:
  -h, --help               display help for command

Commands:
  create [options] <slug>  Create a workspace:
                           .ralphy/workspaces/<slug>/{workspace.json,shared/,projects/,templates/,batches/}
  list                     List workspaces (slug, name, project count)
  show <slug>              Show a workspace: workspace.json + project list
  use <slug>               Set the active workspace (the default home for new
                           projects)
  stats                    Show workspace statistics
  clean [options]          Clean workspace contents
  help [command]           display help for command
```

### `ralphy migrate`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy migrate [options]

One-pass migration of this root to the final layout: workspace/ tree → .ralphy/
root + workspaces (#108), per-project assets/ + refs/ → artifacts/ (#105).
Idempotent; refuses while generation jobs are in flight. Structural relocation:
path strings in manifests/logs/HTML follow their files (NOT a log edit —
invariant #14).

Options:
  --dry-run       Print the full move + rewrite plan without touching disk
  --project <id>  Scope to one project's inner artifacts/ move only (requires
                  the root move to be done already)
  -h, --help      display help for command
```

### `ralphy assets`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy assets [options] [command]

Pull / list / clean assets from the ralphy-assets companion repo

Options:
  -h, --help                                      display help for command

Commands:
  list [options]                                  List required + pool + example assets from the companion repo
  pull [options] <template-slug>                  Download all required assets for a template into the local cache
  pull-key [options] <manifest-key>               Download a single required asset by its manifest key
  install [options] <project-id> <template-slug>  Pull required assets for a template and copy them into a project's asset tree
  pull-pool [options] <ref>                       Download a single pool item by '<kind>/<slug>' (e.g. italian-brainrot-characters/tung-tung-tung-sahur)
  catalog [options]                               Print or regenerate docs/assets-catalog.md from the live manifest (single source of truth)
  unpack [options] <zip>                          Unpack a brand zip into <project>/brand/, flatten nested dirs into kebab-case filenames, drop __MACOSX/ and .DS_Store, suffix collisions with -N. Idempotent on re-run.
  clean                                           Wipe the local asset cache (.ralphy/cache/assets/)
  cache-info                                      Show the asset cache location and what's currently in it
  help [command]                                  display help for command

Examples:
  ralphy assets list
  ralphy assets list --kind <kind>
  ralphy assets pull <template-slug>
  ralphy assets install <project-id> <template-slug>
  ralphy assets unpack ./brand.zip --project my-proj-001
```

### `ralphy example`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy example [options] [command]

Pull / list complete reference projects from the companion repo

Options:
  -h, --help                   display help for command

Commands:
  list [options]               List available example projects
  pull [options] <example-id>  Download an example project tarball and extract
                               it into the active workspace's projects/<as>/
  help [command]               display help for command
```

### `ralphy audio`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy audio [options] [command]

FFmpeg audio recipes (loudnorm, sidechain duck, concat). All wrap
cli/lib/ffmpeg-recipes.ts.

Options:
  -h, --help           display help for command

Commands:
  loudnorm [options]   EBU R128 loudness normalization (TikTok / Reels target
                       -16 LUFS by default)
  sidechain [options]  Duck music under voice via sidechain compressor → single
                       mixed file
  mix-music [options]  Overlay a music bed onto a video at a fixed volume — no
                       ducking, no fades. Single-call surface for A/B preview
                       workflows.
  concat [options]     Lossless concat of audio segments via the concat demuxer
  help [command]       display help for command
```

### `ralphy video`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy video [options] [command]

FFmpeg video recipes (extract-segment, burn-subs, tonemap-hdr, concat). Wraps
cli/lib/ffmpeg-recipes.ts.

Options:
  -h, --help                 display help for command

Commands:
  extract-segment [options]  Cut a re-encoded segment between start/end seconds
                             (frame-accurate)
  frame [options] <clip>     Extract a single frame (i2v anchor / QA still /
                             poster). `--at` accepts a numeric seconds value or
                             the literal `last` (`-sseof -1`).
  extend [options] <clip>    Last-frame i2v continuation: extracts the last
                             frame of <clip> and runs a new generation anchored
                             on it. Records `input.extends: <clip>` lineage in
                             the gen-log.
  optimize [options]         Re-encode with x264 CRF + tune for noise/grain
                             content. Preserves visual content; shrinks 4-8x for
                             noisy footage.
  burn-subs [options]        Burn an .srt file into the video (call last in the
                             chain — MarginV=90 safe-zone)
  tonemap-hdr [options]      HDR HLG/PQ → Rec.709 SDR via zscale + tonemap
                             (default algo: hable)
  smart-crop [options]       Detect speaker face bboxes in a source video and
                             write face-bboxes.json. Output is consumed by
                             HyperFrames smart-reframe overlays (used by the
                             podcast-clip template) to follow the active speaker
                             with a virtual 9:16 camera, eliminating letterbox
                             bars on horizontal sources.
  add-music [options]        Mix a music bed over the video's existing audio
                             (SFX gets attenuated). Music auto-trims to video
                             length with a fade-out tail.
  vhs [options]              VHS post-process chain: chroma shift + sine drift +
                             film grain + vignette + slight desat/contrast.
  compress [options]         x264 CRF + faststart for social-shareable
                             deliverables. Default CRF 23 (`--social` is
                             implicit).
  grade [options]            Apply a named color-grade preset
                             (tv-commercial-soft|tv-commercial-strong|cinematic-teal-orange|analog-horror).
  concat [options]           Lossless concat of video segments (must share
                             codec/resolution)
  boomerang [options]        Boomerang / ping-pong loop: forward playback + the
                             clip reversed, concatenated into a seamless
                             back-and-forth loop (classic Instagram boomerang).
                             Drops audio (add a music bed in the compose/render
                             step). Output is ~2x the source length.
  help [command]             display help for command
```

### `ralphy image`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy image [options] [command]

Image post-processing recipes (cutout, fit, …). Wraps cli/lib/image/cutout.ts.

Options:
  -h, --help         display help for command

Commands:
  cutout [options]   Background removal for stickers / mascots. `--bg chroma`
                     uses ffmpeg `colorkey` (single-color match, fast). `--bg
                     flood` walks the canvas in headless Chromium from the four
                     corners and clears only the connected background —
                     preserves the die-cut outline + interior white islands (per
                     the free-air-vpn-stickerpack lessons; u2net cuts them off).
  fit [options]      Alpha-trim + scale. `--long N` sets the long-edge target
                     preserving aspect; `--trim-alpha` removes transparent
                     margins first (essential for stickers); `--telegram` is
                     shorthand for `--trim-alpha --long 512` (TG sticker spec).
  crunch [options]   Authentic PS1 / PlayStation-1 crunch: bilinear downscale
                     (kills high-poly/texture detail) → 16-bit rgb565
                     framebuffer (colour banding) → nearest-neighbour upscale
                     (crunchy aliased pixels). Removes the 'clean / cartoonish'
                     feel of a modern render so a generated still reads as a
                     real PS1 screenshot. `--scale` controls harshness (higher =
                     harsher).
  convert [options]  Format + resize + quality on a still (issue #103): PNG →
                     JPG, WebP → PNG, downscale-to-fit (`--max WxH`, never
                     upscales), metadata strip (`--strip` drops EXIF / C2PA /
                     colour profiles — the #021 anchor-prep recipe as a reusable
                     verb). Target format inferred from the --out extension.
                     ImageMagick one-invocation when installed, ffmpeg fallback
                     otherwise.
  help [command]     display help for command
```

### `ralphy banner`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy banner [options]

Print the Ralphy ASCII banner

Options:
  -h, --help  display help for command
```

### `ralphy eval`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy eval [options] [command]

Evaluate the quality of a rendered video

Options:
  -h, --help              display help for command

Commands:
  video [options] <path>  Run the full eval pipeline on a single mp4 (structure
                          / audio / captions / vision) and write eval-report.md
                          + eval.json
  help [command]          display help for command
```

### `ralphy research`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy research [options] [command]

Topic-level research: aggregate multiple sources into a single report

Options:
  -h, --help                              display help for command

Commands:
  start [options] <topic>                 Create a research topic directory (workspace/research/<slug>/)
  add-source [options] <url>              Pull a URL and run the full ref chain, linking the result into a topic
  synthesize [options] <topic>            Cross-source LLM synthesis → report.md + sources.json
  show <topic>                            Print the topic state (sources, question, last synthesis)
  list                                    List all research topics under workspace/research/
  run [options] <query...>                Deep research: plan → fan-out search → fetch → summarize → cited report
  scrape-profile [options] <profile-url>  Distill one creator's style: yt-dlp lists N recent videos, vision-analyzes each, writes a style-sheet.md
  help [command]                          display help for command
```

### `ralphy prompts`

```
____        __      __         
   / __ \____ _/ /___  / /_  __  __
  / /_/ / __ `/ / __ \/ __ \/ / / /
 / _, _/ /_/ / / /_/ / / / / /_/ / 
/_/ |_|\__,_/_/ .___/_/ /_/\__, /  
             /_/          /____/   
        UGC video pipeline · ralphy.dev

Usage: ralphy prompts [options] [command]

Prompt cookbook + library lookup (02.03 / 02.0L)

Options:
  -h, --help       display help for command

Commands:
  library          Library by goal/situation
  modes [options]  List cookbook mode files for video / voice / music
  help [command]   display help for command
```
