Skip to main content
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, always run suggest before reaching for a model — there’s a good chance the format already exists.

​
Two tiers, one resolver

TiersourceAudienceStorage
Public content librarypublicshipped to everyoneSupabase (hosted; the same library /library serves, read via cli/lib/library/client.ts)
workspace/templates/workspaceuser-local, gitignoredper-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: workspace/templates/<id>.json
  • Dir: workspace/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. 
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.

​
ralphy template list

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 <id>

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 <id>

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

​
ralphy template create / register / delete

# 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 ./workspace/templates/my-format

# Remove
ralphy template delete my-new-format
create writes a flat workspace/templates/<id>.json; for richer templates, scaffold a dir under workspace/templates/<id>/ manually and use register to add it to the registry. See Template format.

​
Slug resolution

Given a slug, the resolver walks in this order:
  1. workspace/templates/<id>/template.json (dir, workspace)
  2. workspace/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; 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).