Resource CRUD

The unified create / list / show / update / delete shape that brand, persona, ref, template, asset, batch, and friends all share.

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

Resource	Storage	Purpose
brand	.ralphy/workspaces/<ws>/shared/brands/<id>.json	Voice, do/don’t, lockup, palette
persona	.ralphy/workspaces/<ws>/shared/personas/<id>.json	Character archetype + signature delivery
ref	.ralphy/workspaces/<ws>/shared/refs/<id>.json + .ralphy/references/<slug>/	Source clips and analysis artifacts
template	public library (library.json on Bunny CDN) and .ralphy/workspaces/<ws>/templates/<id>/ (local)	Vibe-reference or vibe-style blueprints
batch	.ralphy/workspaces/<ws>/batches/<id>/	N projects from one template, see Working: batches
asset	.ralphy/registry.json entry	Tracked file references (uploaded refs, lookups)
workspace	n/a (operates on dirs)	Workspace-level utilities
profile	profiles/<nick>/	Shareable workspace dumps
config	.ralphy/config.json	Key/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.

Related

• Project verbs — project is the most-used CRUD resource
• Templates — template CRUD plus the loader semantics
• Concepts: workspace — where each resource physically lives
• Per-resource reference: /reference/cli/brand, /reference/cli/persona, /reference/cli/ref, /reference/cli/template, /reference/cli/batch, /reference/cli/asset, /reference/cli/workspace, /reference/cli/profile, /reference/cli/config