Project verbs

new, clone, project create / list / show / update / delete, plus log and timeline.

Projects are the unit of work in ralphy. Every generation, render, and log line is keyed by a project ID. This page walks the verbs that create, inspect, and mutate projects, plus the append-only log surface that backs every project’s memory. Per-verb flag detail lives in the auto-generated reference.

Two creation paths

ralphy new is the agent-facing entry-point: it creates a project under ~/.ralphy/projects/<id>/ (CWD-independent), seeds BRIEF.md from the argument, and touches the three append-only logs.

ralphy new "Spring 2026 ad for Acme dental floss"
# → { project_id, path, brief }

ralphy new --id summer-launch-001         # empty shell
ralphy new "office walkthrough" --id office-walk-001

ralphy project create is the structured form for when you have a brand, persona, and template already picked. It writes to .ralphy/workspaces/<ws>/projects/<id>/ inside the active project root and registers the entity in .ralphy/registry.json.

ralphy project create \
  --name "Summer Launch" \
  --brand acme \
  --persona founder-monologue \
  --template italian-brainrot \
  --brief "Spring drop for the floss line" \
  --duration 15

Use ralphy new when starting from a brief; use ralphy project create when scripting a batch from a template.

ralphy clone <url-or-ref>

clone is a meta-verb. Given a public URL (TikTok / Reels / Shorts / X) or an existing ref slug, it chains four back-stage verbs — ref pull → ref frames → ref analyze → ref blueprint — then writes a new vibe-style template under .ralphy/workspaces/<ws>/templates/clone-<slug>/.

ralphy clone https://tiktok.com/@x/video/72939...
ralphy clone existing-ref-slug --strict-look --prompt-only
ralphy clone https://www.instagram.com/reel/abc --as-template winter-vibe-002

--strict-look mirrors palette and grading in the blueprint; --prompt-only skips music and voice extraction; --as-template overrides the derived id. Full surface: /reference/cli/clone.

ralphy project list

Lists every registered project with derived status — done, assets, render, prompts, scenario, or draft. Status is recomputed from the filesystem on every call, so a stale registry never lies.

ralphy project list
ralphy project list --status draft
ralphy project list --brand acme

The JSON shape is an array of { id, name, status, brand, persona, platform }.

ralphy project show <id>

Inspect a single project. By default it prints the canonical metadata; flags drill into sub-resources.

ralphy project show demo-001
ralphy project show demo-001 --scenario
ralphy project show demo-001 --prompts
ralphy project show demo-001 --assets
ralphy project show demo-001 --status
ralphy project show demo-001 --tree    # full dir tree + sizes (depth 4)

--tree returns { project, root, fileCount, totalBytes, tree: [{ path, bytes }] } — useful for confirming what landed on disk before a render.

ralphy project update / delete

ralphy project update demo-001 --status review --duration 20
ralphy project delete demo-001

delete is registry-aware: it removes the entry from registry.json and the on-disk dir together. Per AGENTS.md invariant #13, this is the only blessed cleanup path. Don’t rm -rf .ralphy/workspaces/<ws>/projects/<id> by hand — you’ll desync the registry.

ralphy project log + timeline

Every project keeps three append-only JSONL files under logs/. The verbs that read and write them:

# Read the generation log (every model call with cost + path)
ralphy project log demo-001
ralphy project log demo-001 --kind video

# Read a single chronological timeline (generations + prompts + assets merged)
ralphy project timeline demo-001

# Append a user prompt
ralphy project log-prompt demo-001 --stage intake --text "make it shorter"

# Append a user asset (uploaded ref)
ralphy project log-asset demo-001 --path ./ref.jpg --note "lookbook page 4"

The three log files are the single source of truth for project memory — see Generation log. The CLI is append-only by contract: never rewrites, never truncates. See AGENTS.md invariant #13.

ralphy project score / transcribe / verify / clone

Three utility verbs that don’t fit the CRUD shape:

ralphy project score demo-001         # run the scenario quality gate
ralphy project transcribe demo-001    # transcribe every VO clip + write captions
ralphy project verify demo-001        # ffprobe + manifest sanity check
ralphy project clone demo-001 --as demo-002   # duplicate the project

score raises E_GATE_SCENARIO when the scenario fails; see Error catalog. verify is the cheap pre-render check that catches missing slots, codec mismatches, and aspect drift.

Project ID conventions

The canonical shape is {context}-{NNN} (e.g. spring-2026-001). ralphy new falls back to YYMMDD-HHMMSS when no brief is supplied. Slot IDs inside a project follow {scene-id}-{type}-{descriptor} (e.g. scene-01-bg-image) — see Generation verbs.

Related

• Concepts: projects — the workspace layout
• Concepts: generation log — the JSONL shapes
• Resource CRUD — the unified verb shape that project follows
• cli/commands/project.ts, cli/commands/new.ts, cli/commands/clone.ts