ralphy

An autonomous UGC-video studio in one repo.
Drive it from a chat. Get an mp4 in ~8 minutes.

What is this

ralphy is a CLI + Remotion render pipeline + Claude Code skill library that turns a one-line prompt into a finished UGC-style mp4. It wires up:

• OpenRouter — image (gemini-3-pro-image-preview), video (kling-v3.0-pro, veo-3.1, seedance-2.0, …), LLM/vision, transcription
• ElevenLabs — voiceover (eleven_multilingual_v2 / eleven_v3) + music beds
• Remotion — composition, captions, transitions, final render
• A local job queue — SQLite + a detached worker, so an agent can fire 11 generations and walk away

You drive the whole thing from chat ("make a video in soviet style about <thing>") or from the CLI directly. No SaaS, no dashboard, no FAL/Vercel/OpenAI wrappers — just two API keys.

Two keys, two commands, two minutes. Then ask the chat for a video.

Demo

You          ▸ Make a 30s explainer in soviet-nostalgic style about my new espresso machine.
ralphy       ▸ Reading template `soviet-nostalgic`… picked.
             ▸ Pulling reference assets from ralphy-assets… ✓ (3 files, cached)
             ▸ Drafting scenario (6 scenes, ≤10-word hook, problem→solution)… ✓
             ▸ Queueing 6 image gens + 6 video gens + 1 VO + 1 music…    job id 41
             ▸ [watch] 13/13 done · $7.84 spent · 6:42 elapsed
             ▸ Rendering composition… workspace/projects/espresso-001/render/final.mp4
             ▸ Done. 30.0s · 1080×1920 · 24 fps.

Total cost on the default stack: ~$8–12 per 30s video. Speed: ~8 min cold-start, ~25 min for a 10-batch.

Install

Pick your channel

All four ship the same statically linked binary (~60–120 MB) — bun runtime + bytecode-compiled TS, no node_modules to manage. They differ only in install plumbing:

• brew — sha256-pinned tap alecs5am/homebrew-tap, tracks the latest release; auto-upgrade via brew upgrade.
• curl / install.sh — strips macOS Gatekeeper quarantine, appends ~/.local/bin to your shell rc (~/.zshrc / ~/.bashrc / fish config) idempotently, prints an "upgraded X.Y.Z → A.B.C" delta when overwriting an older install.
• PowerShell / install.ps1 — drops ralphy.exe to %LOCALAPPDATA%\Programs\ralphy, strips Windows MOTW (mark-of-the-web) so SmartScreen doesn't prompt, appends the dir to your user PATH (HKCU:\Environment).
• npm — thin scoped wrapper @alecs5am/ralphy; the postinstall hook downloads the matching binary from the GitHub Release.

After installing, open a new shell and:

ralphy --version          # sanity check (also: ralphy -v, ralphy version)
ralphy help               # top-level command index
ralphy help generate      # man-style detail for any subcommand

Or from source

curl -fsSL https://bun.sh/install | bash       # bun
brew install ffmpeg                             # ffmpeg (or apt install ffmpeg)
git clone https://github.com/alecs5am/ralphy.git
cd ralphy && bun install
bun run ralphy -- --version

Setup

Two flavours: interactive wizard (humans) and non-interactive (agents / CI).

Interactive:

ralphy setup

Walks you through linking the project dir, entering OPENROUTER_API_KEY + ELEVENLABS_API_KEY (verified via API ping), and optionally importing a public profile. Idempotent — re-runs are safe.

Non-interactive (for AI agents in a terminal, or CI):

# Keys from explicit flags
ralphy setup -y --project-dir /path/to/ralphy \
  --openrouter-key sk-or-... --elevenlabs-key xi-...

# Or pipe a key in via stdin (no shell history leak)
cat or-key.txt | ralphy setup -y --project-dir /path/to/ralphy --openrouter-key -

# Or pick them up from the current env
OPENROUTER_API_KEY=sk-or-... ELEVENLABS_API_KEY=xi-... \
  ralphy setup -y --project-dir /path/to/ralphy --keys-from-env

Emits a structured JSON summary, exits non-zero on real failures (bad project dir, unverified key without --allow-unverified). Full flag list: ralphy setup --help.

Verify:

ralphy doctor          # blockers: []  ← green

First video

claude          # launch Claude Code in this folder

Then in chat:

"Set up the dev env and make me a video in soviet style about <your product>"

The agent reads AGENTS.md, picks a template, drafts a scenario, queues asset generations, renders the mp4, and hands you the path. You watch progress via ralphy queue watch if you want a live dashboard.

What you can ask for

Talk to it like a producer — say what you want delivered, not how.

Direct CLI

Full command surface lives in CLI.md. Highlights:

# Discovery
ralphy --help                              # top-level
ralphy <resource> <action> --help          # always check before guessing flags
ralphy models list                         # 13 OR video models, current price + param matrix
ralphy template suggest "<utterance>"      # rank templates against free text

# Single-shot generation (validated against per-model whitelists)
ralphy generate video --project p-001 --slot scene-01-vid \
  --model kwaivgi/kling-v3.0-pro --duration 5 --aspect-ratio 9:16 \
  --first-frame .../scene-01-img.png --prompt "..." --dry-run

# Queue + daemon (fire-and-forget)
ralphy generate video ... --queue --queue-tag scenes      # enqueue
ralphy queue watch                                         # ANSI dashboard
ralphy queue logs <id> --follow                            # tail one job

# CRUD on projects, templates, refs, brands, personas, batches, profiles
ralphy project list / show / log / timeline / score
ralphy template list / show / use / suggest

# Render
ralphy render <project-id> --loudnorm

JSON by default (parse it). -p switches to human tables.

Architecture

ralphy/
├── cli/                  ralphy CLI (TypeScript, bun runtime)
│   ├── commands/         resource subcommands (generate, queue, daemon, render, …)
│   └── lib/              providers/ jobs/ ffmpeg-recipes/ or-catalog/ …
├── src/
│   ├── lib/              durable Remotion components (captions, overlays, layouts)
│   └── videos/<name>/    per-video compositions
├── templates/            committed template pack (vibe-reference + vibe-style)
├── workspace/            generated files (gitignored)
│   ├── projects/<id>/    per-project assets, manifests, logs, render
│   └── .ralph/           jobs.sqlite, daemon.pid, or-catalog cache
├── profiles/             committed dumps of users' workspaces (additive imports)
├── docs/playbooks/       role/domain instruction docs (researcher, scenarist, …)
├── tests/                unit + integration + live (env-gated)
├── AGENTS.md             playbook router (auto-loaded into the system prompt)
├── CLAUDE.md             repo orientation
├── MODELS.md             current model snapshot (read before any model call)
└── CLI.md                ralphy command cheatsheet

The runtime stack is two providers (OPENROUTER_API_KEY, ELEVENLABS_API_KEY), one render engine (Remotion), one local SQLite queue, and a detached bun worker. No SaaS, no dashboard, no agent runtime.

Templates & profiles

• Templates ship in two roots — templates/ (repo-public, committed) and workspace/templates/ (user-local, gitignored). Workspace overrides repo on id collision. Two kinds today: vibe-reference (full production templates with composition + reference example) and vibe-style (prompt cookbooks: hooks, camera vocab, worked examples). Roster: docs/templates-index.md.

• Profiles are committed dumps of someone's workspace/. Import is additive — your local files aren't overwritten, registry and logs are merged. Heavy renders are dropped from exports unless --include-renders.

  ralphy profile list
  ralphy profile import <nick>             # additive
  ralphy profile import <nick> --overwrite # replace conflicts
  ralphy profile export <your-nick>
  

• Heavy assets (trend music, full example projects) live in the ralphy-assets companion repo. They auto-pull on ralphy template use into workspace/.ralph/asset-cache/ (SHA-256 verified, no auth).

Documentation

Contributing

git clone https://github.com/alecs5am/ralphy.git
cd ralphy && bun install

# Dev loop
bun run dev                    # Remotion Studio (composition preview)
bun run lint                   # eslint src/ + tsc
bun test                       # full suite (unit + integration)
bun run test:unit              # unit only
bun run test:integration       # integration only
bun run test:live              # live API tests (RUN_LIVE_TESTS=1, ~$0.15)

# Build binaries
bun run build:bin              # all platforms → dist/binaries/
bun run build:bin:current      # current platform only

# Release
git tag v0.2.0 && git push --tags    # release.yml builds + uploads to GitHub Release

A pre-commit hook (husky 9) runs unit + integration tests on every commit. CI runs the same on push/PR via test.yml.

PRs welcome — especially new templates, new model entries in MODELS.md, and bug fixes in cli/lib/providers/. For non-trivial changes, open an issue first.

FAQ

~/.local/bin isn't in PATH. Add to ~/.zshrc (or ~/.bashrc):

export PATH="$HOME/.local/bin:$PATH"

Then source ~/.zshrc.

Link the project: ralphy setup --link /path/to/ralphy. Or just cd into the project folder.

Use ralphy setup -y with --openrouter-key, --elevenlabs-key, --keys-from-env, or stdin (--openrouter-key -). See the Setup section above.

Just two — OPENROUTER_API_KEY (image / video / LLM / vision / transcribe) and ELEVENLABS_API_KEY (voice + music). FAL / Vercel / OpenAI direct / Replicate are not used; the v2 stack is consolidated on OpenRouter.

Yes — .env is in .gitignore. ralphy setup validates each key with an API ping before saving (skip with --no-verify).

Yes — every command is a ralphy verb. The chat layer just routes prompts to playbooks; you can drive the CLI by hand. See CLI.md and docs/cli-spec.md.

A 30s vertical UGC video on the default kling stack: ~$8–12 (image gens, 6×5s video clips, 1 VO, 1 music bed). Use --dry-run on any ralphy generate to preview cost without spending. See MODELS.md for the per-model price table.

Re-run the install script — it overwrites the binary:

curl -fsSL https://raw.githubusercontent.com/alecs5am/ralphy/main/install.sh | sh

Pin a version: RALPHY_VERSION=v0.2.0 curl ... | sh.

rm ~/.local/bin/ralphy
rm -rf ~/.config/ralphy

The cloned repo is removed with rm -rf.

Open an issue — happy to add -baseline builds to the release artefacts.

License

UNLICENSED — private project. Use at your own risk; no warranty. Author may relicense before a public release.