The retro command.

Eight commands cover the full retrograde workflow: scaffold, inspect, validate, emit. The CLI walks @import graphs by default — single-file .retro programs work the same way.

Commands at a glance

retro init

Scaffold a .retro file from a one-line prompt. Writes a skeleton with @future, @shape, @flow, and @impl placeholders ready to fill.

$ retro init "todo list with persistence and stable ordering"
  created todo-list.retro

retro status

Quick read on a program: which levels are filled, which extensions and imports are declared, whether structural rules pass.

$ retro status examples/multi-system/main.retro

system AppMain

  ✓ @header  (4 fields)
     summary: Top-level app composing Auth + Billing
  ✓ @future  (1 guarantee, 0 behaviors)
  ✓ @shape   (1 module, 0 version choices)
  ✓ @flow    (1 transition)
  ✗ @impl    empty

  imports
     → Auth = ./auth.retro
     → Billing = ./billing.retro

  validity: structural PASS

retro validate

Run the hybrid validator. Default behavior walks the @import graph and validates every loaded module. Use --no-imports to validate a single file in isolation.

Options

Output

$ retro validate --structural-only main.retro
Loaded 3 modules via @import graph.

STRUCTURAL CHECK: 0 errors, 0 warnings

Exit codes

• 0 — clean. Structural rules pass; semantic prompts (if requested) printed for review.
• 1 — structural errors found, or load failed.

retro emit

Extract every @impl block (across the import graph) into real files under the given output directory. Multi-file @impl blocks (file "src/x.py" { ... }) preserve their declared paths; single-file @impl writes <system-name>.<ext>.

Options

$ retro emit examples/whiteboard.retro --out ./src
  ./src/collabwhiteboard.html

retro delta

Show @delta("...") annotations across a program — the in-source change history. Useful for "what's changed and why" reviews without leaving the file.

retro versions

List @version blocks across modules, including dormant alternatives. Each dormant version carries a reason:; this command surfaces them so design alternatives stay visible.

retro viz (experimental)

Launch a live dashboard at localhost:5555 showing the program as a crystal shape (one ring per filled level) and an architecture graph. Marked experimental — works for the four core blocks but doesn't yet render @header, @extension, or unknown extension blocks.

$ retro viz whiteboard.retro
  serving on http://localhost:5555

The @import behavior

By default, every command that takes a .retro file walks the @import graph from that root: validate, status, emit all load every imported file before running. Use --no-imports on any of them to disable graph traversal — useful for sub-file sanity checks.

Path resolution is relative to the file containing the @import (Node/Python convention), not the root. Diamond imports load once. Cycles fail with L003. See /docs for the full loader behavior.

Conversational patterns

If you're using Retro through Claude Code (with the marketplace plugin), you usually invoke the CLI through natural language: