---
title: "Quickstart"
description: "From zero to first mp4 in 5 steps and ~8 minutes."
---

A clean 5-step path. Each step has a one-line **verify** snippet so you know it worked before moving on.

## 1. Install the binary

<CodeGroup>

```bash macOS (Homebrew)
brew install alecs5am/tap/ralphy
```

```bash Linux / macOS (curl)
curl -fsSL https://raw.githubusercontent.com/alecs5am/ralphy/main/install.sh | sh
```

```powershell Windows (PowerShell)
irm https://raw.githubusercontent.com/alecs5am/ralphy/main/install.ps1 | iex
```

```bash npm (cross-platform)
npm install -g @alecs5am/ralphy
```

</CodeGroup>

All four channels ship the same statically-linked binary — pick whichever fits your platform.

**Verify:**

```bash
ralphy --version
```

<Tip>
  If `ralphy: command not found` after `curl install.sh`, open a new shell — the installer appends
  `~/.local/bin` to your shell rc.
</Tip>

## 2. Run the setup wizard

```bash
ralphy setup
```

The wizard is interactive and idempotent — re-running it never overwrites a key that's already set.

<Steps>
  <Step title="Paste API keys">
    Two keys: `OPENROUTER_API_KEY` (image / video / LLM / vision) and `ELEVENLABS_API_KEY` (voice + music). The wizard pings each provider with a cheap probe before saving.
  </Step>
  <Step title="Install the skill bundle">
    Pick your AI agent — Claude Code, Cursor, or Codex — and `ralphy skill install --agent <id>` drops the playbook routing into your agent's config.
  </Step>
</Steps>

**Verify:**

```bash
ralphy doctor
```

You should see `blockers: []`, both keys green, and `bun` + `ffmpeg` detected.

## 3. Create your first project

```bash
ralphy new "Spring 2026 ad for my espresso machine" --id espresso-001
```

Creates a project under `~/.ralphy/projects/espresso-001/` with the canonical layout (`assets/`, `render/`, `logs/`). CWD-independent — works from any directory.

**Verify:**

```bash
ralphy project show espresso-001
```

## 4. Hand the brief to your agent

Open your AI agent (Claude Code, Cursor, etc.) inside the project. The skill bundle from step 2 means it already knows the playbooks. Type a brief like:

```text
Make a 30s explainer for my espresso machine in soviet-nostalgic style.
```

Ralphy will route through the intake playbook: ask 3-5 clarifying questions, draft a plan, then generate scenes one beat at a time. Roughly:

- **6 images + 6 video clips** via OpenRouter (gpt-5.4-image-2, kling-v3.0-pro)
- **1 voiceover + 1 music bed** via ElevenLabs
- **Final composition** via Remotion → mp4

**Verify:**

```bash
ralphy render espresso-001
ls ~/.ralphy/projects/espresso-001/render/
```

You should see `final.mp4`. **~8 minutes cold-start, ~$8–12 in API costs** on the default stack.

## 5. Where to go next

<CardGroup cols={2}>
  <Card title="Concepts" icon="brain" href="/concepts">
    How workspaces, projects, brands, personas, refs, templates, gen-log, and the asset manifest compose into a self-improving loop.
  </Card>
  <Card title="CLI reference" icon="terminal" href="/cli/overview">
    Every verb, every flag, auto-generated from source so it never drifts from the binary.
  </Card>
  <Card title="Cookbook" icon="book" href="/working/generating-assets">
    Worked prompt examples for image / video / voice / music — paste and edit, ship in minutes.
  </Card>
  <Card title="Templates" icon="layer-group" href="/concepts/templates">
    The 42 built-in vibe templates and how to author your own.
  </Card>
</CardGroup>

Need help? Drop a question in [GitHub Discussions](https://github.com/alecs5am/ralphy/discussions) — soft launch in progress.
