---
title: "Templates"
description: "ralphy template list, suggest, use, show, register — slug resolution across repo and workspace."
---

Templates are the reusable shape behind a video — a vibe-reference (full-stack production blueprint) or a vibe-style (prompt cookbook). They live in two locations that the CLI reads transparently, and the right way to discover one is `ralphy template suggest "<utterance>"`. Per [AGENTS.md invariant #10](https://github.com/alecs5am/ralphy/blob/main/AGENTS.md), always run `suggest` before reaching for a model — there's a good chance the format already exists.

## Two tiers, one resolver

| Tier | `source` | Audience | Storage |
|---|---|---|---|
| Public content library | `public` | shipped to everyone | Supabase (hosted; the same library `/library` serves, read via `cli/lib/library/client.ts`) |
| `.ralphy/workspaces/<ws>/templates/` | `workspace` | user-local, gitignored | per-checkout |

The loader resolves slugs across both tiers. Workspace overrides the public tier on collision — letting you edit a published template locally. The public tier degrades gracefully when the library is unreachable (workspace-only + a warning). The old repo-public `templates/<category>/<slug>/` folder was retired in #084.

The workspace tier supports two on-disk layouts:

- **Flat:** `.ralphy/workspaces/<ws>/templates/<id>.json`
- **Dir:** `.ralphy/workspaces/<ws>/templates/<id>/template.json` + `TEMPLATE.md` + `composition.md` and friends

Dir-based templates are preferred — the LLM-readable doc (`TEMPLATE.md`) lives next to metadata.

## ralphy template suggest

The agent's discovery surface. Pass an utterance, get the top-N matching templates ranked by score.

```bash
ralphy template suggest "spring drop, deadpan founder, 15s"
ralphy template suggest "italian brainrot, 9:16, no music" --limit 5
```

Returns `{ matches: [{ slug, score, kind, summary, source }] }`. The scorer is a pure keyword matcher against frontmatter + body — no LLM call, fast and deterministic.

Full surface: [`/reference/cli/template`](/reference/cli/template).

## ralphy template list

```bash
ralphy template list
ralphy template list --kind vibe-style
ralphy template list --kind vibe-reference
ralphy template list --category entertainment-viral
ralphy template list --source public
ralphy template list --source workspace
```

Returns `{ id, kind, source, name, summary }`. Two `kind` values ship today: `vibe-reference` (full-stack production templates with `composition.md` + reference example) and `vibe-style` (prompt cookbooks with hooks + camera vocab + worked example prompts). `source` is `public` (hosted library) or `workspace` (user-local).

## ralphy template show &lt;id&gt;

```bash
ralphy template show italian-brainrot
ralphy template show italian-brainrot --raw   # raw template.json
ralphy template show italian-brainrot --doc   # TEMPLATE.md only
```

The default form returns metadata plus a resolved doc summary. `--raw` and `--doc` are useful when piping into another tool.

## ralphy template use &lt;id&gt;

The verb that wires a template into a project. Validates required inputs (`brand`, `persona`, `refs`, …), pulls every required asset from the companion repo, copies them into the project tree, and writes `TEMPLATE_ORIGIN.md` so the project remembers its source.

```bash
ralphy template use italian-brainrot \
  --project demo-001 \
  --brand acme \
  --persona founder-monologue
```

When a required input is missing, the verb refuses with `E_TEMPLATE_INPUT_MISSING` and names the matching flag.

Full surface: [`/reference/cli/template`](/reference/cli/template).

## ralphy template create / register / delete

```bash
# Author a new template inline
ralphy template create \
  --id my-new-format \
  --kind vibe-style \
  --name "My new format" \
  --summary "..."

# Register an existing dir as a template
ralphy template register my-format --dir ./.ralphy/workspaces/<ws>/templates/my-format

# Remove
ralphy template delete my-new-format
```

`create` writes a flat `.ralphy/workspaces/<ws>/templates/<id>.json`; for richer templates, scaffold a dir under `.ralphy/workspaces/<ws>/templates/<id>/` manually and use `register` to add it to the registry. See [Template format](/advanced/template-format).

## Slug resolution

Given a slug, the resolver walks in this order:

1. `.ralphy/workspaces/<ws>/templates/<id>/template.json` (dir, workspace)
2. `.ralphy/workspaces/<ws>/templates/<id>.json` (flat, workspace)
3. Public content library lookup by slug (Supabase, via `cli/lib/library/client.ts`)

The first hit wins — the workspace tier shadows a public template of the same slug. The library lookup degrades gracefully when Supabase is unreachable (workspace-only).

## Browsing the catalog

The full roster lives on the public [Library](https://www.alecs5am.com/library); `ralphy template list -p` and `ralphy template suggest "<brief>"` are the CLI surfaces. The old repo-public `CATEGORIES.md` / `TOP.md` manifests were retired with the `templates/` folder (#084).

## Related

- [Concepts: templates](/concepts/templates) — the conceptual model
- [Template format](/advanced/template-format) — `template.json` schema
- [Assets](/cli/assets) — `template use` auto-pulls required assets
- [docs/templates-index.md](https://github.com/alecs5am/ralphy/blob/main/docs/templates-index.md) — full index
- [cli/commands/template.ts](https://github.com/alecs5am/ralphy/blob/main/cli/commands/template.ts), [cli/lib/templater/loader.ts](https://github.com/alecs5am/ralphy/blob/main/cli/lib/templater/loader.ts)
