---
title: "Picking a template"
description: "ralphy template suggest is the first move. 54 templates, two kinds, five categories — how to pick and what gets copied."
---

A template is Ralphy's compressed knowledge about a specific viral format. Pick the right one and most of the hard decisions — pacing, hook style, camera vocabulary, music policy — are already made for you. Pick the wrong one and you're improvising the basin Ralphy is going to drift into. The CLI's first move on any new brief is `ralphy template suggest "<your brief>"`, and you can run it yourself any time.

## How suggest works

The verb returns a ranked list of up to three matches with a `score` (0-1) and a `tier`. The threshold defaults to 0.7; below that, Ralphy reranks with an LLM ([`google/gemini-2.5-flash`](https://github.com/alecs5am/ralphy/blob/main/cli/commands/template.ts)) to catch paraphrases and multilingual briefs.

```bash
ralphy template suggest "selfie review of my coffee syrup, autumn cozy" --limit 3
```

```json
{
  "results": [
    {
      "slug": "ugc-selfie-product-review",
      "kind": "vibe-style",
      "category": "dtc-commerce",
      "score": 0.91,
      "tier": "primary",
      "description": "Handheld 9:16 UGC selfie product review. Identity-lock via locked product + persona master shots passed as --ref on every gen."
    },
    {
      "slug": "before-after-product",
      "kind": "vibe-reference",
      "category": "dtc-commerce",
      "score": 0.74,
      "tier": "primary",
      "description": "5s pain → 1s reveal → 9s demo. Most reliably converting UGC pattern."
    },
    {
      "slug": "grwm",
      "kind": "vibe-style",
      "category": "creator-lifestyle",
      "score": 0.62,
      "tier": "secondary",
      "description": "Get Ready With Me — dual-layer (visual + storytime)."
    }
  ]
}
```

Three things Ralphy does with that output:

- **Top result is `primary`.** Announces the pick inline ("Using `ugc-selfie-product-review` — handheld 9:16 UGC selfie review. Switch with `ralphy template use <other-slug>` if it's wrong.") and proceeds. Ralphy does not ask "should I use this?" — announce-and-proceed is the action.
- **Top result is `secondary`.** Lists the top three with one-liners and asks once: "These three are close — `<a>`, `<b>`, `<c>`. Which fits, or should I draft from scratch?"
- **Top result is `fallback` (below threshold).** Enters free-form mode. Ralphy says once: "No close template match — drafting from scratch with the vibe-style cookbook" and proceeds via the scenarist playbook.

You can short-circuit the suggest step at any time by naming the slug yourself: "use the `before-after-product` template for this".

## The five categories

Public templates live in the hosted content library (browse on [`/library`](https://www.alecs5am.com/library)); your own live under `.ralphy/workspaces/default/templates/`. Categories are organized by **who's watching** the content, not by visual style. The full roster is on the Library; a quick map:

| Category | Audience | Tone | Count |
|---|---|---|---|
| `b2b-saas/` | Decision-makers, ops, founders | Confident, didactic, ROI-aware | 7 |
| `dtc-commerce/` | Online shoppers — apparel, beauty, nutra, gadgets | Aspirational, peer-evidence, demo-led | 12 |
| `creator-lifestyle/` | Scroll-feed lifestyle, personality-driven | Relatable, first-person, unpolished | 10 |
| `entertainment-viral/` | Pure scroll-stop / meme / brainrot | Punchy, surreal, often AI-native | 15 |
| `cinematic-narrative/` | Aesthetics-first, premium look | Directorial, deliberate, film grammar | 11 |

You don't pick a category by hand — `template suggest` does it for you. The folder structure is navigation aid. Slug resolution is global: `ralphy template use <slug>` works regardless of which category folder the slug lives in, and workspace-local templates ([`.ralphy/workspaces/default/templates/`](/concepts/templates)) override repo templates on id collision.

## The two kinds

Every template is one of two kinds, declared in its `template.json`:

- **`vibe-reference`** — a full-stack production template with `composition.md`, `model-stack.md`, and a `reference-example.md` showing a worked end-to-end render. Five of these ship today. They encode the entire workflow, not just the prompts. Use them when you want a known-good production path with minimal improvisation.
- **`vibe-style`** — a prompt cookbook with `hooks.md`, `prompt-cookbook.md`, and worked example prompts. Thirty-eight ship today. The cookbook is your reference; you (or the scenarist playbook) write the actual scenario from scratch. Use them when you want the vibe + the hook patterns but need flexibility on structure.

`template show <slug>` prints the raw `TEMPLATE.md`:

```bash
ralphy template show ugc-selfie-product-review
```

Add `--json` for the metadata, `--path` for the on-disk location, `-p` for pretty.

## The Top-20 cross-category playlist

For a hand-curated "what's actually moving the needle in 2026" shortlist, sort the public [Library](https://www.alecs5am.com/library) by popularity. It surfaces high-leverage templates across four of the five categories (cinematic-narrative is aesthetic-first, not virality-first). If you're learning Ralphy by doing, walking that shortlist is the test-drive set: each one exercises a different viral pattern.

## Using a template

Once you've picked a slug, scaffold a project:

```bash
ralphy template use ugc-selfie-product-review \
  --project syrup-001 \
  --name "Cinnamon Cold Brew" \
  --brief "selfie review of my coffee syrup, autumn cozy"
```

What lands in `.ralphy/workspaces/default/projects/syrup-001/`:

- **`TEMPLATE_ORIGIN.md`** — which template was used and when. Read by downstream playbooks.
- **`BRIEF.md`** — your `--brief` text, formatted.
- **`scenario.json` skeleton** — pre-filled with the template's beat structure (for `vibe-reference`) or empty for the scenarist to fill (for `vibe-style`).
- **`composition.md`** if the template ships one (vibe-reference only).
- **A pulled asset cache** — if the template declares heavy required assets (gameplay loops, trend music), Ralphy auto-pulls them from the [`ralphy-assets`](https://github.com/alecs5am/ralphy-assets) companion repo into `.ralphy/cache/assets/`. SHA-256 verified, no auth needed.

The `--brand`, `--persona`, and `--ref` flags pre-satisfy the template's requirements if it declares any in `template.json.requires`.

## Customizing after `use`

A scaffolded project is yours to edit. The template provides the starting point; the scenario, prompts, and asset slots become live files under your project. You can:

- Swap the model stack — pass `--model <id>` on any `ralphy generate` call (see [Generating assets](/working/generating-assets)).
- Edit `scenario.json` via the scenarist playbook — "rework scene 3", "shorten the hook", "drop scene 4".
- Add new scenes — append to `scenario.json.scenes` and follow the same slot-id convention.
- Promote your customizations into a new template via `ralphy template create --from-project <id> --slug <new-slug>` (producer playbook). Don't invent templates from scratch — extract them from a project that already shipped.

## When no template fits

Free-form mode is a first-class path. Ralphy enters it automatically when `template suggest` returns nothing above the threshold, and you can ask for it any time ("ignore the template, draft from scratch"). In free-form, the scenarist playbook drives the scenario from your brief plus the `vibe-style` cookbook entries. You lose the prompt-cookbook scaffolding but gain full flexibility.

## Related

- [Starting a project](/working/starting-a-project) — where `template suggest` slots into intake
- [Templates concept](/concepts/templates) — public library vs workspace, slug resolution
- [Template format](/advanced/template-format) — `template.json`, file layout, requires
- [CLI: templates](/cli/templates) — every flag on every template verb
- [Library](https://www.alecs5am.com/library) — full roster, browsable by category
