Skip to main content
The three entities on this page exist for one reason: keeping identity stable across scenes and across projects. A brand carries the logo, palette, and tone across every video you make for one client. A persona is the recurring on-screen character — the founder, the spokesperson, the cartoon mascot — whose face needs to match between scene-01 and scene-04. A reference is the locked image Ralphy passes as --ref on every generate call so the model can’t drift away from “this exact bottle / this exact face / this exact room”. Get the identity pattern right and you stop fighting model drift; get it wrong and every regen invents a different couch.

​
Brands — for multi-project consistency

A brand is the entity you reuse across projects. Create one when you’ll be making more than one video for the same client or product line. 
ralphy brand create \
  --name "Cinnamon Cold Brew" \
  --slug cinnamon-cold-brew \
  --palette "#7c3a0f,#fff4d6,#1a1a1a" \
  --tone "warm, conversational, autumn-cozy"
The brand object lives in workspace/brands/<slug>/ and carries the logo, palette, tone, and optional default persona. Reference it on any project create: 
ralphy project create --name "Syrup launch hero" --brand cinnamon-cold-brew --id syrup-001
Downstream prompts pick up the brand’s palette and tone automatically. You don’t have to retype “warm, autumn-cozy” into every prompt.

​
Personas — for recurring characters

A persona is the on-screen human (or cartoon, or AI avatar) that has to look the same in every scene. Create one when more than one scene shows the same character, or when you’ll reuse the character across projects. 
ralphy persona create \
  --name "Anna the barista" \
  --slug anna-barista \
  --archetype "creator-friend" \
  --voice-id elevenlabs-voice-xyz \
  --master-shot workspace/personas/anna-barista/master.png
The master-shot is the canonical reference image — the locked face Ralphy passes as --ref on every scene gen so identity doesn’t drift between scene-01 and scene-04. The eight named archetypes live in workspace/personas/ARCHETYPES.md. Attach a persona to a project at create time, or pass --persona <slug> on a template use call: 
ralphy template use ugc-selfie-product-review \
  --project syrup-001 \
  --persona anna-barista

​
References — the per-call lock

A reference is a single image (or multiple) you pass to a generate call with --ref. Ralphy converts a local path to a data: URI automatically; a URL passes through. Two patterns matter: The master-shot pattern. Lock the product and the persona as standalone images first, then pass them as --ref on every scene gen. This is the single highest-leverage technique in the art-director playbook — multi-scene projects without master refs spend real money on “they keep sitting on different couches” or “the bottle label changed shape between scenes”. 
# 1. Generate the product master shot once.
ralphy generate image \
  --project syrup-001 \
  --slot product-master \
  --prompt "750ml amber syrup bottle, kraft label, cinnamon-stick illustration, studio lighting, 1:1"

# 2. Lock the persona master shot.
ralphy generate image \
  --project syrup-001 \
  --slot persona-master \
  --prompt "Anna the barista, 30s, warm smile, kitchen lighting" \
  --ref workspace/personas/anna-barista/master.png

# 3. Every downstream scene passes BOTH as --ref.
ralphy generate image \
  --project syrup-001 \
  --slot scene-02-bg \
  --prompt "Anna pours syrup into iced coffee, kitchen counter, autumn morning light" \
  --ref workspace/projects/syrup-001/assets/product-master.png \
  --ref workspace/projects/syrup-001/assets/persona-master.png
Multi-ref. Most image models accept multiple --ref flags. gemini-3-pro-image-preview is the default and the canonical multi-ref model — it holds face / wardrobe / product identity across 2-3 refs and tolerates ≥4 concurrent calls. Switch to gpt-5.4-image-2 only when label typography on a hero product shot must read crisp (it caps at 1 concurrent). See Generating assets for the per-modality model picks.

​
The reference-required gate

This is AGENTS invariant #3. Read it once and the rest of this section makes sense. The gate fires for named real entities the model cannot fabricate — and only those:
  • A specific person (“Elon Musk”, “Cristiano Ronaldo”, your own face).
  • A recognizable brand product (“Coca-Cola can”, “iPhone 16”, “Old Spice bottle”).
  • A recognizable IP (“Mickey Mouse”, “Pikachu”, “Iron Man”).
When the gate fires and no reference is attached, Ralphy refuses to generate. You get a concrete ask: either attach a reference image, or pass --no-ref-consent "<reason>" on the specific failing call. The gate does not fire for generic product or lifestyle work. “My coffee shop’s new pastry”, “a no-name workout app”, “a barista named Anna” — these proceed without a ref because there’s no real-world identity for the model to fabricate. The CLI floor is ralphy ref check <project-id> [--text "<brief>"], which runs an offline classifier (no LLM cost) over the scenario and brief. 
ralphy ref check syrup-001
# → { "needs_reference": false, "reasons": [], "entities": [] }

ralphy ref check oldspice-relaunch-001
# → { "needs_reference": true, "reasons": ["named-brand-product"], "entities": ["Old Spice"] }
When the gate fires but you genuinely want to proceed without a reference — maybe you’re sketching a comp, maybe the model handles the entity well enough for your purposes, maybe you’ll attach the ref later — pass --no-ref-consent "<reason>" on the failing call: 
ralphy generate image \
  --project oldspice-relaunch-001 \
  --slot scene-01-bg \
  --prompt "Old Spice deodorant on bathroom counter, morning light" \
  --no-ref-consent "comp pass — will lock the real bottle ref before final"
The string after --no-ref-consent is mandatory and must be non-empty. The CLI appends a stage: "no-ref-consent" entry to user-prompts.jsonl for that project so the next session — and your future self — can see you deliberately accepted the quality hit. See Generation log for the JSONL contract.
--no-ref-consent is per-call. It does not propagate to the next generate invocation. If you want to skip the gate on three calls, pass the flag three times — that’s a deliberate friction point so you can’t accidentally turn the gate off for an entire batch.

​
Attaching refs after the fact

If you attached refs late and want them logged for the gen-log trail, use ralphy project log-asset: 
ralphy project log-asset syrup-001 \
  --kind ref-url \
  --source https://example.com/canonical-bottle.png \
  --purpose product-ref \
  --note "official packshot from the client"
This appends to user-assets.jsonl — append-only, never overwrites, like every other log under workspace/projects/<id>/logs/ (AGENTS invariant #13).

​
Editing a brand or persona

The standard CRUD verbs work on brand and persona just like every other resource: 
ralphy brand list -p
ralphy brand show cinnamon-cold-brew -p
ralphy brand update cinnamon-cold-brew --tone "warm, conversational, with a wink"
ralphy persona update anna-barista --master-shot path/to/new-master.png
Updates are write-in-place on the brand or persona record itself. They do not touch projects that already reference the brand or persona — your existing renders stay as they were. If you want the new tone reflected in syrup-001, you have to regenerate the affected slots; Ralphy never silently re-renders past work.