> ## Documentation Index
> Fetch the complete documentation index at: https://ralphy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Install

> Clone the repo, open it in Claude Code, ask Claude to set you up. The standalone binary is the alternative.

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

```bash theme={"dark"}
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.

<Note>
  You need Claude Code on your machine for this path. Install it from [claude.com/claude-code](https://claude.com/claude-code) — free for personal use. Cursor, Copilot, and Codex work too once Ralphy is set up; see [Connect your editor](/quickstart/connect-editor).
</Note>

## What you'll need

* **`git`** — to clone the repo.
* **Claude Code** (or another supported editor — see [Connect your editor](/quickstart/connect-editor)).
* **`bun` and `ffmpeg`** on the host. Claude will install them if missing.
* **An [OpenRouter](https://openrouter.ai/keys) key** — covers image, video, LLM, vision, transcription.
* **An [ElevenLabs](https://elevenlabs.io/app/settings/api-keys) 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:

```bash theme={"dark"}
ralphy doctor -p
```

```text theme={"dark"}
 ★ 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.

<Tabs>
  <Tab title="macOS (brew)">
    ```bash theme={"dark"}
    brew tap alecs5am/tap
    brew install ralphy
    ```

    Brew handles upgrades — `brew upgrade ralphy` picks up new releases.
  </Tab>

  <Tab title="Linux/macOS (curl)">
    ```bash theme={"dark"}
    curl -fsSL https://raw.githubusercontent.com/alecs5am/ralphy/main/install.sh | sh
    ```

    The installer detects your OS and arch, drops the binary at `~/.local/bin/ralphy`, appends a PATH line to your shell rc, and strips quarantine on macOS. Reload your shell or open a new terminal.

    Pin a version or change the install dir:

    ```bash theme={"dark"}
    RALPHY_VERSION=v0.3.0 RALPHY_BIN_DIR=$HOME/bin \
      curl -fsSL https://raw.githubusercontent.com/alecs5am/ralphy/main/install.sh | sh
    ```
  </Tab>

  <Tab title="npm (cross-platform)">
    ```bash theme={"dark"}
    npm i -g @alecs5am/ralphy
    ```

    The npm package wraps the same binary. Works on Windows without WSL.

    Upgrades: `npm update -g @alecs5am/ralphy`.
  </Tab>
</Tabs>

Then run setup yourself:

```bash theme={"dark"}
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:

```bash theme={"dark"}
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 -`.

<Tip>
  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.
</Tip>

## 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](/quickstart/first-video).

## Related

* [Your first video](/quickstart/first-video) — drive a render from chat
* [Connect your editor](/quickstart/connect-editor) — wire Cursor, Copilot, or Codex if you don't use Claude Code
* [setup & doctor reference](/cli/setup-doctor) — every flag and edge case
* [Install playbook](https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/ralphy-install.md) — canonical source
* [OpenRouter keys](https://openrouter.ai/keys) and [ElevenLabs keys](https://elevenlabs.io/app/settings/api-keys)