Skip to main content
Ralphy has a small surface but an opinionated middle. The agent in your editor reads playbooks and calls verbs. The ralphy CLI mutates a workspace on disk. The workspace is append-only and gitignored. Every model call is logged, every regen is a new version, and every brief that names a real-world entity hits a refusal gate until you attach a reference. These pages cover the moving parts so you can reason about what Ralphy will do before it spends your money.

​
Read these in order

If you are new, start with What is Ralphy and Architecture. After that the pages stand alone — each one cites its source-of-truth doc in the repo so you can follow the trail.

What is Ralphy

AI film studio in your terminal. Who it serves, what it replaces, what makes it refuse.

Architecture

Three moving parts: agent, CLI, workspace. How they pass work back and forth.

Workspace

Directory layout. What is canonical, what is scratch, what survives a wipe.

Projects

One project equals one video. Lifecycle, on-disk layout, the registry.

Brands and personas

Reusable identity: who the video is from, and who is in it.

References

The ref-required gate. When Ralphy refuses, and how the override works.

Templates

Two kinds, five categories, 54 entries. Read this before improvising.

Asset catalog

The companion-repo pool: brainrot characters, gameplay loops, trend music.

Generation log

The append-only contract. Schemas for the three JSONL files. Versioning rules.

Playbooks and skills

Role docs read on demand vs. slash-invocable workflows. Two namespaces.

​
What “concepts” means here

A concept page describes a durable idea — the workspace layout, the ref gate, the log schema. Concepts do not change between commands. The CLI reference and the cookbook recipes do change — when a verb gets a new flag, the reference page regenerates. When you want to understand why ralphy generate writes a .v2 file instead of overwriting .v1, you stay here. If you came here looking for a verb signature, the CLI reference is at /cli/generation-verbs. If you came looking for “how do I make my first video,” start with /quickstart/first-video.