> ## Documentation Index
> Fetch the complete documentation index at: https://ralphy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={"dark"}
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

```bash theme={"dark"}
# 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](/reference/cli/setup) 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](/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](/cli/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:

```bash theme={"dark"}
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:

```bash theme={"dark"}
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.

```bash theme={"dark"}
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](https://github.com/alecs5am/ralphy/blob/main/AGENTS.md), 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](/cli/generation-verbs).
* **`render`** — the HyperFrames pipeline. See [Rendering verbs](/cli/rendering-verbs).
* **`doctor` / `setup` / `status`** — env-level utilities. See [Setup and doctor](/cli/setup-doctor).
* **`assets`** (plural) — pulls from the companion repo, not local CRUD. See [Assets](/cli/assets).

## Related

* [Project verbs](/cli/project-verbs) — `project` is the most-used CRUD resource
* [Templates](/cli/templates) — `template` CRUD plus the loader semantics
* [Concepts: workspace](/concepts/workspace) — where each resource physically lives
* Per-resource reference: [/reference/cli/brand](/reference/cli/brand), [/reference/cli/persona](/reference/cli/persona), [/reference/cli/ref](/reference/cli/ref), [/reference/cli/template](/reference/cli/template), [/reference/cli/batch](/reference/cli/batch), [/reference/cli/asset](/reference/cli/asset), [/reference/cli/workspace](/reference/cli/workspace), [/reference/cli/profile](/reference/cli/profile), [/reference/cli/config](/reference/cli/config)