Skip to main content
Ralphy is agent-driven. The fastest install is: clone the repo, open it in Claude Code, ask Claude to set you up. Claude reads AGENTS.md, routes to the install playbook, runs ralphy doctor, walks you through the key wizard, and confirms. You end with a working ralphy invocation and a project ready for the first brief.

​
The default path — clone + Claude Code

git clone https://github.com/alecs5am/ralphy.git ugc-cli
cd ugc-cli
claude
In chat, say:
set me up
Claude does the rest:
  1. Runs which bun, which ffmpeg, which ralphy. Tells you what’s missing.
  2. Installs bun and/or ffmpeg for you (interactive — you confirm each step).
  3. Drops the ralphy binary onto your PATH if it isn’t there yet.
  4. Runs ralphy setup for the two API keys. You paste each one; the wizard pings the provider to verify before saving.
  5. Runs ralphy doctor one last time. Greens across the board means you’re ready.
The whole thing takes 3-5 minutes on a clean machine, most of it spent grabbing OpenRouter and ElevenLabs keys.
You need Claude Code on your machine for this path. Install it from claude.com/claude-code — free for personal use. Cursor, Copilot, and Codex work too once Ralphy is set up; see Connect your editor.

​
What you’ll need

  • git — to clone the repo.
  • Claude Code (or another supported editor — see Connect your editor).
  • bun and ffmpeg on the host. Claude will install them if missing.
  • An OpenRouter key — covers image, video, LLM, vision, transcription.
  • An ElevenLabs key — covers voiceover and music.
You don’t need Vercel, FAL, or OpenAI direct. Two keys, one repo, one chat.

​
Verify

After Claude finishes, run it yourself to confirm: 
ralphy doctor -p

 ★ ralphy v0.3.0
   cwd      /Users/you/ugc-cli
   project  /Users/you/ugc-cli

   Dependencies
   ✓ bun
   ✓ ffmpeg

   API keys
   ✓ OPENROUTER_API_KEY        OpenRouter
   ✓ ELEVENLABS_API_KEY        ElevenLabs

   ✓ ready
If anything’s red, the blockers array tells you the exact next command. Tell Claude “ralphy doctor is failing” and it’ll fix it.

​
Standalone binary (alternative)

If you don’t want to clone the repo — for CI, scripts, or a one-off render — install the binary directly. You still need a ugc-cli checkout somewhere on disk for templates and asset cache; the wizard asks for its path. 
brew tap alecs5am/tap
brew install ralphy
Brew handles upgrades — brew upgrade ralphy picks up new releases.
Then run setup yourself: 
ralphy setup
The wizard asks for the path to your ugc-cli checkout (if you don’t have one, git clone https://github.com/alecs5am/ralphy ugc-cli first), accepts each key, pings the provider to verify, and writes them to <project>/.env. For CI or scripts, drive setup non-interactively: 
ralphy setup -y \
  --openrouter-key sk-or-... \
  --elevenlabs-key xi-... \
  --project-dir ~/code/ugc-cli
Or pipe a key from stdin: cat key.txt | ralphy setup -y --openrouter-key -.
Prefer direnv? After ralphy setup writes .env, add an .envrc alongside it with dotenv so the keys load on cd. Ralphy reads from process env; either source works.

​
Why clone + Claude Code is the default

Ralphy is built around an agent reading playbooks. The repo is the playbook bundle — AGENTS.md, docs/playbooks/, templates/, MODELS.md. When Claude Code opens the repo, it gets the routing table on every turn, picks the right playbook per request, and runs ralphy for every model call. With the standalone binary alone, you have the engine but not the routing — you’d be improvising prompts and skipping the postmortem-validated patterns the repo ships with. In short: the binary runs commands; the repo carries the intelligence. You want both.

​
Next

Drop your first brief into chat — head to Your first video.