### Install and Setup Voicebox from Source Source: https://github.com/alecs5am/ralphy/blob/main/notes/skills/ad-creative/references/generative-tools.md Clones the Voicebox repository and executes the setup and development build commands. ```bash git clone https://github.com/jamiepine/voicebox.git cd voicebox && make setup && make dev ``` -------------------------------- ### Setup and Development Commands Source: https://github.com/alecs5am/ralphy/blob/main/README.md Commands for cloning the repository, installing dependencies, running tests, and building the project. ```bash git clone https://github.com/alecs5am/ralphy.git cd ralphy && bun install bun test # unit + integration (1,000+ tests) bun run lint # typecheck + project lints (errors / help-examples / skills / agents-md / cli-surface) bun run cli:surface:build # regenerate docs/cli-surface.generated.md bun run build:bin # build cross-platform binaries ``` -------------------------------- ### Verify installation and usage Source: https://github.com/alecs5am/ralphy/blob/main/npm/README.md Commands to check the version, view help, or run the setup process. ```bash ralphy --version ralphy help ralphy setup ``` -------------------------------- ### Run setup wizard Source: https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/core/doctor.md Launches the interactive setup wizard to configure API keys. ```bash ralphy setup ``` -------------------------------- ### Setup and Status Source: https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/core/cli-cookbook.md Commands for system setup, status checks, and binary linking. ```bash ralphy setup ralphy setup --status # JSON (no TUI) ralphy setup --link # link binary to project ralphy setup --unlink ralphy status -p ralphy doctor ``` -------------------------------- ### ralphy example list Source: https://github.com/alecs5am/ralphy/blob/main/docs/cli-surface.generated.md Lists all available example projects that can be pulled into the workspace. ```APIDOC ## ralphy example list ### Description List available example projects from the companion repository. ### Usage `ralphy example list [options]` ``` -------------------------------- ### Execute Ralphy installation and workflow Source: https://github.com/alecs5am/ralphy/blob/main/docs/tester-onboarding.md Follow these steps to install the CLI, verify the environment, configure API keys, and perform a test render. ```bash # 1. Install (pick one) brew install alecs5am/tap/ralphy # OR curl -fsSL https://raw.githubusercontent.com/alecs5am/ralphy/main/install.sh | sh # 2. Verify ralphy --version ralphy doctor # should fail until step 3 # 3. Setup ralphy setup # paste OPENROUTER_API_KEY + ELEVENLABS_API_KEY ralphy doctor # should be green now # 4. Install the skill into your AI agent ralphy skill install --agent claude # or cursor / codex # 5. Create a project ralphy new "your one-line brief here" --id tester-001 # 6. Hand the project to your agent # Open Claude Code / Cursor / Codex inside the project dir; # the skill should already be routing through AGENTS.md. # 7. Render and report back ralphy render tester-001 ls .ralphy/workspaces/default/projects/tester-001/render/ # expect final.mp4 ``` -------------------------------- ### Install the package Source: https://github.com/alecs5am/ralphy/blob/main/npm/README.md Install the ralphy wrapper globally using npm. ```bash npm install -g @alecs5am/ralphy ``` -------------------------------- ### Install project dependencies Source: https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/core/doctor.md Installs packages via Bun and verifies the existence of the node_modules directory. ```bash bun install ls -d node_modules >/dev/null 2>&1 && echo "ok" || echo "missing" ``` -------------------------------- ### Install and verify yt-dlp Source: https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/researcher/yt-dlp.md Check if yt-dlp is installed and available on the system path, installing via Homebrew if missing. ```bash which yt-dlp || brew install yt-dlp yt-dlp --version ``` -------------------------------- ### Initialize Template Project Source: https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/intake.md Command to start a project based on a predefined template. ```bash ralphy template use ``` -------------------------------- ### Few-Shot Prompting Example Source: https://github.com/alecs5am/ralphy/blob/main/notes/skills/prompt-engineering-expert/references/techniques.md Use examples to help the model infer label taxonomies, styles, or transformation patterns. ```text Classify support tickets as billing, technical, feature_request, or general. - Ticket: "I was charged twice this month" - Category: billing - Ticket: "The app crashes when I upload a 100MB file" - Category: technical - Ticket: "Could you add dark mode?" - Category: feature_request ## Ticket: "{ticket}" Category: ``` -------------------------------- ### Install Ralphy via Script Source: https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/ralphy-install.md Download and install the latest Ralphy binary using the official installation script. ```bash curl -fsSL https://raw.githubusercontent.com/aleksei-oleinik/ugc-cli/main/install.sh | sh ``` -------------------------------- ### Build Ralphy from Source Source: https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/ralphy-install.md Fallback installation method for when pre-built releases are unavailable. ```bash git clone https://github.com/aleksei-oleinik/ugc-cli.git ~/code/ugc-cli cd ~/code/ugc-cli bun install bun run build:bin -- --current cp dist/binaries/ralphy-* ~/.local/bin/ralphy chmod +x ~/.local/bin/ralphy ``` -------------------------------- ### Install and run ralph Source: https://github.com/alecs5am/ralphy/blob/main/docs/cli-spec.md Methods for executing the ralph CLI via npm, npx, bunx, or global installation. ```bash # Via package.json bin npm run ralph -- project list # Via npx (from the project root) npx ralph project list # Via bunx bunx ralph project list # Globally (if installed) ralph project list ``` -------------------------------- ### Launch the Dashboard Source: https://github.com/alecs5am/ralphy/blob/main/docs/agent-guide.md Start the local dashboard to monitor workspace changes in real time. ```bash # Launch ralph dashboard # http://localhost:4321 ralph dashboard --port 8080 # Or via npm npm run dashboard ``` -------------------------------- ### Ralphy README Structure Template Source: https://github.com/alecs5am/ralphy/blob/main/notes/audit-2026-05/audit.md A recommended layout for the project README, featuring a hero video, installation instructions, and a quick-start guide. ```markdown [hero MP4 30s autoplay muted] # Ralphy Your AI video pipeline as code — fork-able, observable, reproducible. [Tests] [Release] [npm] [Discord] [License Apache 2.0] Claude Code + Ralphy = two API keys, one CLI, a video pipeline you can ship to prod. ## Install brew install alecs5am/tap/ralphy curl -fsSL ... | sh npm install -g @ralphy/cli ## 60-second tour 1. ralphy setup # paste OPENROUTER_API_KEY + ELEVENLABS_API_KEY 2. ralphy doctor # check env 3. ralphy new "Spring espresso ad" --id e1 4. ralphy template suggest "talking head 30s product" 5. ralphy render e1 [expected ASCII output] ## Why Ralphy | Other OSS | Ralphy | |-----------|--------| | Imperative scripts | Append-only genlogs + postmortems | | Generic LLM call | Quality gates refuse-not-warn | | One model | OpenRouter router across Kling/Seedance/Veo/Sora/Nano-Banana | | `interpreter --do-everything` | Playbook discipline + intake gates | | GUI editors | HTML composer (HyperFrames) you version in git | ## Wall of Love [testimonials from Discord/X/HN] ## Architecture [mermaid diagram from the target arch] ## Docs / Community [Mintlify links + Discussions] ``` -------------------------------- ### Install Ralphy via Command Line Source: https://github.com/alecs5am/ralphy/blob/main/README.md Commands to install the Ralphy binary on various platforms. ```bash brew install alecs5am/tap/ralphy ``` ```bash curl -fsSL https://raw.githubusercontent.com/alecs5am/ralphy/main/install.sh | sh ``` ```powershell irm https://raw.githubusercontent.com/alecs5am/ralphy/main/install.ps1 | iex ``` ```bash npm install -g @alecs5am/ralphy ``` -------------------------------- ### ralphy example pull Source: https://github.com/alecs5am/ralphy/blob/main/docs/cli-surface.generated.md Downloads and extracts a specific example project into the active workspace. ```APIDOC ## ralphy example pull ### Description Download an example project tarball and extract it into the active workspace's projects// directory. ### Parameters - **example-id** (string) - Required - The identifier of the example project to download. ``` -------------------------------- ### Local server command Source: https://github.com/alecs5am/ralphy/blob/main/notes/ideas/013-newsroom-carousel-format/source-skill.md Command to start a local development server for previewing the project. ```bash cd [project folder path] && python3 -m http.server 3456 ``` -------------------------------- ### Podcast Repurpose Path Source: https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/scenarist/pacing.md Example directory structure for podcast clip projects. ```bash .ralphy/workspaces//projects/lyadov-podcast-001/ ``` -------------------------------- ### Flat-Lay Prompt Examples Source: https://github.com/alecs5am/ralphy/blob/main/docs/prompts/image/flat-lay.md A collection of specific prompt examples for different product categories and styles. ```text Create a top-down flat lay of the [product] on a clean studio surface, balanced composition, soft even lighting, realistic material texture, minimal shadow, commercial product photography style. ``` ```text Top-down flat lay product photography of a sleek wireless earbuds case on a clean white desk surface, minimal props (single silver pen and folded paper), soft window-like lighting from left, gentle shadows, shot on Sony A7IV with 35mm, f/6.3, modern tech aesthetic, crisp details --ar 4:5 ``` ```text Top-down product flat lay of a gold watch on white marble with subtle gray veining, minimal luxury props (silk ribbon and small ring), soft diffused studio lighting, clean shadows, shot on Canon R3 with 50mm, f/7.1, premium catalog styling, sharp metal detail --ar 4:5 ``` ```text Create a clean product composition showing the [product] from front, side, and slightly angled views in one frame, consistent lighting, neutral background, preserve exact color and shape, catalog-ready. ``` ```text Professional product photography of a sustainable soap bar in kraft paper packaging, placed on textured linen fabric with dried botanical accents, soft daylight from right, natural shadows, warm earthy color grading, shot on Canon R5 with 50mm, f/5.6, organic lifestyle aesthetic --ar 4:5 ``` -------------------------------- ### Verbatim Prompt Examples Source: https://github.com/alecs5am/ralphy/blob/main/docs/prompts/image/closeup-with-person.md A collection of specific prompt examples for various product categories and interaction types. ```text Show a model naturally using the [product] in a realistic setting, keep the product fully accurate in shape, size, and branding, product clearly visible, natural pose, commercial lifestyle photography. ``` ```text Show elegant hands interacting with the [product], no face visible, clean composition, shallow depth of field, realistic commercial lighting, focus on product and usage. ``` ```text Photorealistic lifestyle product photo of a well-groomed hand holding a serum dropper bottle, clean neutral background, soft diffused studio light, realistic skin texture and natural nails, label sharp and readable, shot on Sony A7R IV with 85mm, f/3.2, modern beauty ad style --ar 4:5 ``` ```text Ultra-realistic product lifestyle photo of a model wearing a delicate gold necklace, close-up from collarbone to chin, soft studio lighting, skin texture natural, necklace sparkling with controlled highlights, minimal background, shot on Nikon Z9 with 105mm, f/4, luxury campaign look --ar 4:5 ``` ```text Photorealistic ecommerce lifestyle image of two hands opening a premium product box on a clean table, tissue paper and branded insert visible, bright softbox lighting, top-down angle, shot on Sony A7IV with 35mm, f/5.6, crisp details, modern DTC unboxing aesthetic --ar 4:5 ``` ```text Photorealistic beauty product photo of a hand applying a lipstick swatch on the forearm with the product tube beside it, clean neutral background, soft diffused light, accurate color, sharp focus on texture, shot on Canon R5 with 100mm macro, f/5.6, editorial cosmetics look --ar 4:5 ``` ```text Photorealistic lifestyle product shot of an athletic person gripping a branded shaker bottle, gym background softly blurred, dramatic side lighting with sweat highlights, confident energetic mood, shot on Sony A1 with 85mm, f/2.8, shallow depth of field, ad-ready composition --ar 4:5 ``` ```text Show the [product] being held naturally in one hand to communicate scale, realistic proportions, clean background, clear focus on the product, no distortion, e-commerce lifestyle photography. ``` ```text Photorealistic product shot of a person pouring freshly brewed coffee from a branded carafe into a ceramic cup, warm window light, steam visible, cozy morning mood, focus on product branding, shot on Canon R6 with 50mm, f/2.8, natural motion blur controlled, editorial lifestyle --ar 4:5 ``` -------------------------------- ### Download Guide Videos Source: https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/researcher/site-extract.md Command to download tutorial videos for topic research using yt-dlp. ```bash yt-dlp -f "best[ext=mp4]/best" --no-playlist -o ".ralphy/research//videos/.mp4" "" ``` -------------------------------- ### Flipper Zero Product-DNA Example Source: https://github.com/alecs5am/ralphy/blob/main/guidelines/cgi-product-renders/guideline.md A concrete example of a product-DNA paragraph for the Flipper Zero device. ```text Subject: The Flipper Zero device — a landscape-orientation handheld multi-tool, roughly 100mm by 40mm by 25mm thick. WHITE plastic body (BOTH top and bottom cases are white plastic). Orange accents ONLY: bright orange D-pad cluster (5-way circular navigation pad with directional arrow and a center select button) located on the right half of the front face; bright orange rectangular bezel framing the rectangular OLED screen on the left half of the front face; bold orange embossed text reading "FLIPPER" along the lower front below the screen and D-pad. Small black round BACK button just to the right of the D-pad. The 1.4-inch monochrome OLED screen displays a pixel-art dolphin face with the katakana text フリッパー next to it. Tiny green LED indicator below screen. MicroSD card slot on the bottom edge near the right corner. USB-C port and rocker button on the right edge. iButton contact pad and small dolphin logo on the back. ``` -------------------------------- ### Manage Hyperframes with CLI Source: https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/hyperframes.md Commands for browsing the registry and installing specific components into project workspaces. ```bash # Discover bunx hyperframes catalog # browse the registry # Install one into your project bunx hyperframes add kinetic-slam .ralphy/workspaces//projects/ # Wire it into index.html (the skill walks you through it) ``` -------------------------------- ### Cinematic Establishing Prompt Source: https://github.com/alecs5am/ralphy/blob/main/docs/prompts/video/pika.md Example prompt for the cinematic-establishing mode. ```text a lone lighthouse silhouette, stands against a stormy sea, rocky coastline at dusk, cinematic anamorphic register, wide 24mm slow dolly-in, dramatic side-light through breaking clouds, waves crash in rhythmic foreground motion ``` -------------------------------- ### Packaging and Ingredients Macro Prompt Source: https://github.com/alecs5am/ralphy/blob/main/docs/prompts/image/macro-detail.md Example prompt for a structured product scene featuring packaging and surrounding ingredient elements. ```text Photoreal product photography scene featuring [PRODUCT + PACKAGING], single set only, brand and label must be clean and undistorted. Arrangement: product centered; exactly [N] ingredient elements placed around it: [ingredient 1], [ingredient 2] ... positioned near base, not covering the label. Surface: [marble / matte stone / light wood], clean and dry unless specified. Lighting: soft diffused top light, controlled specular highlights on packaging, subtle shadow grounding the product. Camera: 50mm lens, eye-level, shallow depth of field, label sharp and readable. Background: simple, minimal, no patterns. Hard exclusions: no extra text, no fake slogans, no additional products, no hands, no watermarks. ``` -------------------------------- ### Common Ralphy CLI Patterns Source: https://github.com/alecs5am/ralphy/blob/main/CLI.md Examples for bootstrapping, dry-running generations, queuing batch jobs, and inspecting model configurations. ```bash # Bootstrap from an agent / CI, no TUI. Reads keys from current env vars. ralphy setup -y --project-dir /path/to/ugc-cli --keys-from-env # Same, but pipe a key in from stdin (no shell history leak) cat or-key.txt | ralphy setup -y --project-dir /path/to/ugc-cli --openrouter-key - --elevenlabs-key xi-... # Dry-run a video gen to see resolved request + cost ralphy generate video --project p-001 --slot scene-01-vid --prompt "..." --duration 5 --model kwaivgi/kling-v3.0-pro --dry-run # Queue 11 portrait clips with first-frame anchor, then render after all complete for i in 01 02 ... 11; do ralphy generate video --project p-001 --slot scene-$i-vid --first-frame .../scene-$i-img.png \ --prompt "..." --duration 5 --queue --queue-tag scenes done ralphy queue watch # ANSI dashboard until all done ralphy render p-001 --loudnorm # Suggest a template from a free-form ask ralphy template suggest "talking-head educational explainer 45s" # Inspect what kling supports right now ralphy models show kwaivgi/kling-v3.0-pro ``` -------------------------------- ### Product Shot Prompt Examples Source: https://github.com/alecs5am/ralphy/blob/main/docs/prompts/image/product-shot.md Various prompt examples for different product categories and styles, ranging from pure white backgrounds to luxury editorial looks. ```text Place the [product] centered on a pure white background, keep the exact shape, proportions, branding, label text, and material finish, use soft studio lighting, realistic shadow directly under the product, e-commerce packshot style, no props, no extra objects. ``` ```text Place the [product] in a clean studio setup with a light gray seamless background, soft diffused lighting, subtle natural shadow, product fully visible, sharp edges, realistic reflections if the material is glossy, premium e-commerce photography. ``` ```text Turn the [product] into a floating studio product image on a clean neutral background, preserve exact product geometry, add a soft shadow below to ground it, keep all visible details realistic and accurate. ``` ```text Photoreal high-end ecommerce packshot of a single [PRODUCT], exact design: [material], [color], [finish], [logo placement], [dimensions/proportions]. Camera: straight-on product photography, 70mm lens, tripod, centered, no perspective distortion, sharp edges, full product in frame. Lighting: large softbox key light from above-left, gentle fill from right, controlled specular highlights, no blown highlights, realistic soft shadow under product. Background: seamless pure white (#FFFFFF), no texture, no gradients, no props. Output: 1:1 square, product fills ~70% of frame, tack sharp focus. Hard exclusions: no extra products, no added accessories, no alternate logo, no text, no watermark, no random branding, no reflections showing a room. ``` ```text Photorealistic studio product photography of a single premium skincare bottle centered on a seamless pure white background, soft diffused key light with gentle shadow under the base, crisp label readability, minimal reflections, shot on Canon R5 with 85mm lens, f/8, ultra-sharp focus, ecommerce listing style, high resolution, natural color accuracy --ar 4:5 ``` ```text Ultra-realistic product photo of a matte black fragrance bottle on glossy black acrylic with subtle mirror reflection, dramatic strip softbox highlights, deep shadows, cinematic luxury mood, shot on Sony A7R IV with 50mm lens, f/5.6, editorial lighting, clean background falloff, high-end campaign look --ar 4:5 ``` ```text Professional product photo of a vitamin supplement jar on a clear acrylic pedestal, seamless light gray background, bright airy softbox lighting, realistic contact shadow and subtle reflections, sharp label, shot on Canon R6 with 70mm, f/8, commercial catalog quality, neutral color grading --ar 4:5 ``` -------------------------------- ### Product Lifestyle Prompt Source: https://github.com/alecs5am/ralphy/blob/main/docs/prompts/video/pika.md Example prompt for the product-lifestyle mode. ```text a ceramic coffee mug with a pastel logo, sits on a sunlit windowsill beside an open book, cozy home kitchen, lifestyle warm naturalistic register, locked 50mm, soft morning sun from screen-right, steam curls upward in slow loops ``` -------------------------------- ### Create Social Content Units via CLI Source: https://github.com/alecs5am/ralphy/blob/main/docs/superpowers/specs/2026-07-13-repository-split-workspace-social-units-design.md Example commands for creating post, thread, and article units within a workspace. ```bash ralphy unit create --workspace acme --slug launch-post --format post \ --from drafts/launch.md --destination telegram --destination x ralphy unit create --workspace acme --slug launch-thread --format thread \ --from drafts/thread.json --destination x --destination threads ralphy unit create --workspace acme --slug launch-article --format article \ --from drafts/article.md --destination devto --destination medium \ --destination x-article ``` -------------------------------- ### HyperFrames CLI Usage Examples Source: https://github.com/alecs5am/ralphy/blob/main/docs/cli-surface.generated.md Common command-line patterns for managing HyperFrames projects, including linting, snapshotting, and rendering. ```bash 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 ``` -------------------------------- ### Verify web application build Source: https://github.com/alecs5am/ralphy/blob/main/docs/superpowers/plans/2026-07-13-repository-split-implementation.md Installs dependencies and builds the web application to ensure integrity after extraction. ```bash bun install --frozen-lockfile && bun run build ``` -------------------------------- ### Ralphy Library Command and Examples Source: https://github.com/alecs5am/ralphy/blob/main/docs/cli-surface.generated.md Commands for reading the public content library from Bunny CDN, including usage examples. ```text ____ __ __ / __ \____ _/ /___ / /_ __ __ / /_/ / __ `/ / __ \/ __ \/ / / / / _, _/ /_/ / / /_/ / / / / /_/ / /_/ |_|\__,_/_/ .___/_/ /_/\__, / /_/ /____/ agent content runtime · 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 ``` -------------------------------- ### Render command output log Source: https://github.com/alecs5am/ralphy/blob/main/notes/issues/done/118-render-master-not-auto-versioned.md Example of the console output when a render is performed on an existing project. ```text ralphy: existing asset auto-archived → render/final-social.v1.mp4 (pass --force-overwrite to disable) ``` -------------------------------- ### Optimize Prompt Evaluation Source: https://github.com/alecs5am/ralphy/blob/main/docs/cli-surface.generated.md Example command for running a prompt optimization evaluation using baseline and candidate prediction files. ```bash ralphy eval optimize-prompt --prompt judge.txt --dataset hooks.json --baseline-predictions base.json --candidate-predictions cand.json --candidate cand.txt ``` -------------------------------- ### Manage project assets Source: https://github.com/alecs5am/ralphy/blob/main/docs/cli-surface.generated.md Commands for listing, pulling, installing, and cleaning assets from the companion repository. ```bash ralphy assets list ``` ```bash ralphy assets list --kind ``` ```bash ralphy assets pull ``` ```bash ralphy assets install ``` ```bash ralphy assets unpack ./brand.zip --project my-proj-001 ``` -------------------------------- ### Install Meta Pixel Source: https://github.com/alecs5am/ralphy/blob/main/notes/skills/paid-ads/references/conversion-tracking.md Add this script to the of every page. Replace YOUR_PIXEL_ID with the ID from Meta Events Manager. ```html ``` -------------------------------- ### Verify Installation Status Source: https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/ralphy-install.md Check the status of enabled capabilities to ensure the core pipeline is functional. ```bash ralphy status -p ``` -------------------------------- ### Update the package Source: https://github.com/alecs5am/ralphy/blob/main/npm/README.md Update the globally installed ralphy package. ```bash npm update -g @alecs5am/ralphy ``` -------------------------------- ### ralphy setup Source: https://github.com/alecs5am/ralphy/blob/main/docs/cli-surface.generated.md Configures the Ralphy agent, including API keys for OpenRouter and ElevenLabs, and links the agent to a project directory. ```APIDOC ## ralphy setup ### Description Runs the setup wizard to configure API keys and development services. Supports non-interactive modes for CI/CD environments. ### Options - **--status** (flag) - Print capability status as JSON and exit. - **--link ** (string) - Link ralphy to a project directory. - **--unlink** (flag) - Remove the global project link. - **--non-interactive** (flag) - Run in agent/CI mode without prompts or TUI. - **--openrouter-key ** (string) - Set OPENROUTER_API_KEY. - **--elevenlabs-key ** (string) - Set ELEVENLABS_API_KEY. - **--keys-from-env** (flag) - Load keys from process environment. - **--no-verify** (flag) - Skip API ping verification. ``` -------------------------------- ### Template suggestion output Source: https://github.com/alecs5am/ralphy/blob/main/README.md Example output showing the results of a template suggestion query. ```text ✦ Query: "talking head rant about deadlines" 1. ✓ talking-head ███████████████░ 0.95 strong 2. ✓ story-time ███████████░░░░░ 0.70 strong ``` -------------------------------- ### Uninstall the package Source: https://github.com/alecs5am/ralphy/blob/main/npm/README.md Remove the globally installed ralphy package. ```bash npm uninstall -g @alecs5am/ralphy ``` -------------------------------- ### Initialize and scaffold a project Source: https://github.com/alecs5am/ralphy/blob/main/README.md Commands to create a new project and find a template using natural language. ```bash # 1. Create a project ralphy new "Spring espresso ad" --id espresso-001 # 2. Find a template by free-text utterance ralphy template suggest "talking head rant about deadlines" -p ``` -------------------------------- ### Create Project from Scratch Source: https://github.com/alecs5am/ralphy/blob/main/docs/agent-guide.md Define brand and persona settings manually before creating a new project. ```bash ralph brand create --name "Client" --url https://client.com --primary "#FF6B35" ralph persona create --name "Narrator" --voice "elevenlabs:eleven_v2/rachel" --tone "friendly" ralph project create --name "Product Demo" --brand client --persona narrator --brief "30s TikTok testimonial" ``` -------------------------------- ### Verify ffmpeg installation Source: https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/core/doctor.md Checks the installed version of ffmpeg. ```bash ffmpeg -version 2>&1 | head -1 ``` -------------------------------- ### Vague Prompt Rewrite Example Source: https://github.com/alecs5am/ralphy/blob/main/notes/skills/prompt-engineering-expert/references/examples.md Demonstrates transforming a vague request into a structured, actionable prompt. ```text Analyze this data and tell me what you think. ``` ```text Analyze the sales data to identify: 1. Top 3 products by revenue. 2. Month-over-month trend changes. 3. Customer segments with the highest lifetime value. Return: - Executive summary: 2-3 sentences. - Key metrics table. - Trend analysis with supporting numbers. - 3 recommended actions for Q4 revenue. Use only the provided data. If a metric cannot be calculated, write "Not available" and explain the missing field. ``` -------------------------------- ### Hyperframes CLI Commands Source: https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/hyperframes.md Commands for rendering projects, iterating on compositions, installing registry blocks, and preprocessing media assets. ```bash # Render the project ralphy render ralphy render --fps 60 --quality high # bump quality ralphy render --resolution portrait # 1080×1920 portrait via DPR ralphy render --loudnorm # +EBU R128 -16 LUFS post-pass # Iterate bunx hyperframes preview .ralphy/workspaces//projects/ # live-reload browser preview (foreground) bunx hyperframes lint .ralphy/workspaces//projects/ # validate composition shape bunx hyperframes inspect .ralphy/workspaces//projects/ # visual layout across the timeline bunx hyperframes snapshot .ralphy/workspaces//projects/ # keyframe PNGs for QA bunx hyperframes doctor # env check (node, ffmpeg, chrome) # Install registry blocks (catalog has 70+ items — see Catalog section below) bunx hyperframes add .ralphy/workspaces//projects/ # Asset preprocessing bunx hyperframes tts --text "..." -o artifacts/voiceover/vo.wav bunx hyperframes transcribe --in vo.wav -o captions.json bunx hyperframes remove-background --in shot.mp4 -o shot-alpha.webm ``` -------------------------------- ### Render project examples Source: https://github.com/alecs5am/ralphy/blob/main/docs/cli-surface.generated.md Common usage patterns for the ralphy render command, including basic rendering, output customization, and quality settings. ```bash ralphy render spring-001 ``` ```bash ralphy render proj-001 --loudnorm ``` ```bash ralphy render proj-001 --output ./out.mp4 ``` ```bash ralphy render proj-001 --fps 60 --quality high ``` ```bash ralphy render arena-rocker-001 --from-clip raw.mp4 --loudnorm ``` ```bash ralphy render proj-001 --no-compress # master only, skip final-social.mp4 ``` ```bash ralphy render proj-001 --social-crf 18 # higher-quality (larger) social cut ``` -------------------------------- ### Lip Gloss Wand Macro Prompt Source: https://github.com/alecs5am/ralphy/blob/main/docs/prompts/image/macro-detail.md Example prompt for capturing liquid beauty products with shimmer and glossy highlights. ```text Extreme close-up macro product shot of a lip gloss wand with visible shimmer texture and glossy highlights, shallow depth of field, creamy bokeh background in soft beige, shot on Canon R5 with 100mm macro lens, f/4, ultra-realistic liquid texture, high resolution beauty photography --ar 4:5 ``` -------------------------------- ### Create a new project Source: https://github.com/alecs5am/ralphy/blob/main/docs/cli-surface.generated.md Scaffolds a new project directory with a canonical layout using a brief or ID. ```bash ____ __ __ / __ \____ _/ /___ / /_ __ __ / /_/ / __ `/ / __ \/ __ \/ / / / / _, _/ /_/ / / /_/ / / / / /_/ / /_/ |_|\__,_/_/ .___/_/ /_/ /_\__, / /_/ /____/ agent content runtime · ralphy.dev Usage: ralphy new [options] [brief...] Create a new project under /projects// with a canonical layout. Lightweight on-ramp — pass a brief to seed BRIEF.md or just --id 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 Project id slug (default: derived from brief or YYMMDD-HHMMSS) --name Display name (default: title-cased id) --brand Brand id (registry lookup) --persona Persona id (registry lookup) --template Template id --platform Target platform (default: "tiktok") --aspect-ratio Aspect ratio (default: "9:16") --duration 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 ``` -------------------------------- ### Classification Few-Shot Template Source: https://github.com/alecs5am/ralphy/blob/main/notes/skills/prompt-engineering-expert/references/examples.md Template for performing classification tasks using few-shot examples. ```text Classify each item into exactly one category: - bug: broken or incorrect behavior - feature_request: new capability or enhancement - question: user asks how something works - other: none of the above Examples: - Input: "The export button does nothing" - Category: bug - Input: "Can you add CSV import?" - Category: feature_request - Input: "Where do I find my invoices?" - Category: question Input: "{input}" Category: ``` -------------------------------- ### Prefilling and Output Anchors Source: https://github.com/alecs5am/ralphy/blob/main/notes/skills/prompt-engineering-expert/references/techniques.md Use prefilling to guide the model toward a specific output format. ```text Return only this JSON object: - { - "summary": "", - "risks": [], - "unknowns": [] - } ``` -------------------------------- ### Create Project from Template Source: https://github.com/alecs5am/ralphy/blob/main/docs/agent-guide.md Initialize a new project using an existing template to maintain consistent formatting. ```bash ralph template list # see what's available ralph template show soviet-nostalgic # read TEMPLATE.md ralph template use soviet-nostalgic \ --project client-spring-001 \ --name "Client Spring Ad" \ --brief "..." # → .ralphy/workspaces//projects/client-spring-001/ with TEMPLATE_ORIGIN.md (pointer to template docs) # and standard subdirectories (artifacts/, logs/, scripts/, render/). # The scenario is written fresh through /ralph-ugc:create-scenario, using TEMPLATE.md as a vibe-reference. ``` -------------------------------- ### CLI Output Formatting Source: https://github.com/alecs5am/ralphy/blob/main/docs/cli-spec.md Examples of standard JSON output versus human-readable pretty-printed output for CLI commands. ```bash $ ralph project list [ {"id": "spring-001", "name": "Spring Ad", "status": "done", "brand": "acme", "createdAt": "2026-03-29T10:00:00Z"}, {"id": "spring-002", "name": "Summer Ad", "status": "assets", "brand": "acme", "createdAt": "2026-03-29T11:00:00Z"} ] ``` ```bash $ ralph project list --pretty ID Name Status Brand Created spring-001 Spring Ad done acme 2h ago spring-002 Summer Ad assets acme 1h ago 2 projects ``` -------------------------------- ### Suggest Templates for Cold-Start Briefs Source: https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/intake.md Use these commands to identify appropriate media formats and style templates when a user provides a generic content request. ```bash ralphy template suggest --help ``` ```bash ralphy template suggest "" --format ``` -------------------------------- ### Initialize and Render Remotion Projects Source: https://github.com/alecs5am/ralphy/blob/main/notes/skills/ad-creative/references/generative-tools.md Commands for setting up a new Remotion project and executing renders for single or batch data-driven videos. ```bash # Create a new Remotion project npx create-video@latest # Render a single video npx remotion render src/index.ts MyComposition out/video.mp4 # Batch render from data npx remotion render src/index.ts MyComposition --props='{"data": [...]}' ``` -------------------------------- ### Initialize Template Usage Source: https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/intake.md Load a specific template for a project with a defined brief. ```bash ralphy template use --project --brief "" ``` -------------------------------- ### Install LinkedIn Insight Tag Source: https://github.com/alecs5am/ralphy/blob/main/notes/skills/paid-ads/references/conversion-tracking.md Place this script before the closing body tag on every page of your website. ```html ``` -------------------------------- ### Using a Template Source: https://github.com/alecs5am/ralphy/blob/main/docs/skills-vs-templates.md Load a specific template for a project with a defined brief for content generation. ```bash ralphy template use --project --brief "" ``` -------------------------------- ### Install TikTok Pixel Source: https://github.com/alecs5am/ralphy/blob/main/notes/skills/paid-ads/references/conversion-tracking.md Include this script in the of every page to initialize the TikTok tracking pixel. Replace 'YOUR_PIXEL_ID' with your actual pixel identifier. ```html ``` -------------------------------- ### Change-One-Thing Canonical Example Source: https://github.com/alecs5am/ralphy/blob/main/docs/prompts/image/iteration-edit.md A concrete example of the master template applied to a specific change request. ```text Use the previous image as the base. Keep the product identity exactly the same: same shape, proportions, color, material, logo placement, and camera angle. Keep lighting and background unchanged. Change only: [ONE CHANGE], e.g., 'background color from #FFFFFF to #F4F1EA' or 'add a softer shadow'. Do not add props. Do not change framing. Do not change the product. Hard exclusions: no style change, no text, no watermark, no extra objects. ``` -------------------------------- ### Execute Render Preflight and Render Source: https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/agent-production-contract.md Commands to validate project settings and generate the final video output. ```bash ralphy editor preflight ralphy render ``` -------------------------------- ### Define the benchmark example schema Source: https://github.com/alecs5am/ralphy/blob/main/benchmarks/README.md The structure of an individual example object within the benchmark set. ```typescript { label: "good"|"acceptable"|"bad", sourceUrl?, mediaRef?, features: string[], notes } ``` -------------------------------- ### Create and scaffold an image-pack project Source: https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/modes/image-pack.md Initializes a new image-pack project with the specified ID and kind, creating the necessary directory structure and configuration files. ```bash ralphy project create --id --kind image-pack ralphy project image-pack --kind [--count N] ``` -------------------------------- ### Ralphy Blueprint Command and Examples Source: https://github.com/alecs5am/ralphy/blob/main/docs/cli-surface.generated.md Commands for capturing and inspecting reproduction-grade blueprints, including usage examples. ```text ____ __ __ / __ \____ _/ /___ / /_ __ __ / /_/ / __ `/ / __ \/ __ \/ / / / / _, _/ /_/ / / /_/ / / / / /_/ / /_/ |_|\__,_/_/ .___/_/ /_/\__, / /_/ /____/ agent content runtime · 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] Capture a self-contained Blueprint for a unit into units//blueprint/ (append-only) list List units that have a captured blueprint/ + which versions exist show [options] Print a unit's latest blueprint.json use [options] 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 ``` -------------------------------- ### Install Google tag in HTML Source: https://github.com/alecs5am/ralphy/blob/main/notes/skills/paid-ads/references/conversion-tracking.md Place this script in the section of every page on your website. Replace AW-XXXXXXXXX with your specific Conversion ID. ```html ``` -------------------------------- ### Scaffold, preview, and render Source: https://github.com/alecs5am/ralphy/blob/main/README.md Commands to apply a template, perform a cost-preview, and render the final project. ```bash # 3. Scaffold from the chosen template (sourced from the hosted library) ralphy template use talking-head --id espresso-001 # 4. Cost-preview before spending a cent ralphy generate image --project espresso-001 --slot scene-01-bg \ --prompt "studio packshot, white seamless, 50mm, photoreal" --dry-run # 5. Render the project to mp4 ralphy render espresso-001 ``` -------------------------------- ### Manage configuration Source: https://github.com/alecs5am/ralphy/blob/main/docs/cli-spec.md Commands for listing, retrieving, and setting configuration values. ```bash ralph config list # Show all settings ralph config get # Get a value ralph config set # Set a value ralph config set default.aspect-ratio 9:16 ralph config set default.fps 30 ralph config set default.platform tiktok ralph config set default.voice ralph config set api.openrouter-key ralph config set api.elevenlabs-key ralph config set render.concurrency 3 ralph config set render.quality production ``` -------------------------------- ### Manage Video Templates via CLI Source: https://github.com/alecs5am/ralphy/blob/main/docs/cli-spec.md Commands for creating, registering, listing, and using video templates from repo or workspace roots. ```bash # Create flat template into workspace (warns if it shadows a repo template) ralph template create --name "Product Testimonial" --from-project ralph template create --name "Before/After" --from-file ./my-template.json # Register existing dir template (workspace or repo) in the local registry ralph template register # Read (lists both repo and workspace; each row tagged with `source`) ralph template list # all templates from both roots ralph template suggest "" # ranked match by tags + metadata ralph template show # prints TEMPLATE.md for dir, JSON for flat ralph template show --path # path only (repo or workspace, whichever wins) ralph template show --meta # structured manifest facets (dir only): requires/scenes/cost/references # Scaffold new project from template (works with either source) ralph template use \ --project \ --name "My Video" \ --brief "One-line brief" # → creates .ralphy/workspaces//projects// with: # - standard subdirectories (artifacts/, logs/, scripts/, render/) # - TEMPLATE_ORIGIN.md (pointer to the template with a reading list) # - BRIEF.md (if --brief was passed) # Intentionally does NOT create scenario.json — the scenario is written fresh through scenarist playbook # using TEMPLATE.md as a vibe-reference. # Delete (workspace-only; refuses on repo templates) ralph template delete ``` -------------------------------- ### Suggest a template based on a brief Source: https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/meta.md Use this command to find a matching media format or template library based on a provided brief. ```bash ralphy template suggest "" --format ``` -------------------------------- ### ralphy project status Source: https://github.com/alecs5am/ralphy/blob/main/docs/cli-surface.generated.md Get machine-readable pipeline status. ```APIDOC ## ralphy project status ### Description Retrieve machine-readable pipeline status. Use --contract for full Unit-lifecycle ledger. ### Parameters - **id** (string) - Required - The project identifier. - **--contract** (flag) - Optional - Alias for --lifecycle; returns full Unit-lifecycle ledger. ``` -------------------------------- ### Abstract Motion Graphic Prompt Source: https://github.com/alecs5am/ralphy/blob/main/docs/prompts/video/pika.md Example prompt for the abstract-motion-graphic mode. ```text a glowing geometric pattern of interlocking triangles, slowly rotates and pulses, deep blue void, motion-graphic flat register, locked centered camera, neon backlight glow, particles dissipate outward at each pulse ```