Skip to main content
Most ralphy resources follow the same five-verb shape: create, list, show <id>, update <id>, delete <id>. Once you know how brand works you know how persona, ref, template, batch, asset, workspace, profile, and config work. This page documents the contract; the auto-gen reference covers per-resource flags.

​
The shape

ralphy <resource> create [--flags]
ralphy <resource> list [--filters]
ralphy <resource> show <id>
ralphy <resource> update <id> [--flags]
ralphy <resource> delete <id>
Every CRUD verb returns JSON by default and pretty-prints on TTY. delete removes both the on-disk file and the registry entry.

​
Worked example: brand

# Create
ralphy brand create \
  --name "Acme Dental" \
  --voice-tone "deadpan-professional" \
  --do "real product, clean countertop" \
  --dont "claymation, neon"

# List
ralphy brand list

# Inspect one
ralphy brand show acme-dental

# Update — additive: pass only the fields you want to change
ralphy brand update acme-dental --voice-tone "deadpan-quirky"

# Delete (registry-aware)
ralphy brand delete acme-dental
The same pattern applies to every resource below. Use ralphy <resource> --help for the create-time flag set; the auto-gen reference has the full surface.

​
Resource map

ResourceStoragePurpose
brandworkspace/.ralph/brands/<id>.jsonVoice, do/don’t, lockup, palette
personaworkspace/.ralph/personas/<id>.jsonCharacter archetype + signature delivery
refworkspace/.ralph/refs/<id>.json + workspace/references/<slug>/Source clips and analysis artifacts
templatetemplates/<id>/ (repo) and workspace/templates/<id>/ (local)Vibe-reference or vibe-style blueprints
batchworkspace/batches/<id>/N projects from one template, see Working: batches
assetworkspace/.ralph/assets/<id>.jsonTracked file references (uploaded refs, lookups)
workspacen/a (operates on dirs)Workspace-level utilities
profileprofiles/<nick>/Shareable workspace dumps
configworkspace/.ralph/config.jsonKey/value settings — see Env + config
For ref and template, the resource layer is the cheap CRUD shape; the heavy lifting (URL pulls, vision analyses, template loading) lives in dedicated verbs — ralphy ref pull/frames/analyze/blueprint, ralphy template use/suggest.

​
Filters on list

Every list returns the full set by default and accepts targeted filters. Common ones: 
ralphy project list --status assets
ralphy ref list --kind video
ralphy template list --kind vibe-style
ralphy batch list --status running
Pipe to jq for arbitrary post-filtering: 
ralphy brand list --json | jq '.[] | select(.voice_tone | contains("deadpan"))'

​
Create vs. update

create requires a --name and rejects on collision (E_ALREADY_EXISTS). update requires the id and is additive — fields you don’t pass stay unchanged. There’s no “patch” / “replace” distinction; the verb merges into the existing JSON. 
ralphy persona create --name "Founder monologue" --tone "earnest, slightly tired"
# → { id: "founder-monologue", name, tone, ... }

ralphy persona update founder-monologue --do "soft eye contact, small hand gestures"
# additive — `tone` and `name` persist

​
Delete is registry-aware

delete <id> removes the on-disk JSON and the registry entry together. Per AGENTS.md invariant #13, this is the only blessed deletion path. Don’t rm files directly — you’ll desync the registry and the next list will lie.

​
What’s not in CRUD

  • generate — model calls. Not a resource verb; see Generation verbs.
  • render — the HyperFrames pipeline. See Rendering verbs.
  • doctor / setup / status — env-level utilities. See Setup and doctor.
  • assets (plural) — pulls from the companion repo, not local CRUD. See Assets.