ChooChoo

The choochoo CLI validates specs, records agent traces, and serves documentation. For installation, see the Installation guide. For a hands-on walkthrough, see the Quickstart.

Global options

choochoo --version   # Show version number
choochoo --help      # Show help for any command
choochoo help <cmd>  # Show help for a specific command

Setup

`init`

Scaffold a content directory with example files for domains, teams, data products, contracts, schemas, and more.

choochoo init [options]

Flag	Description
`-d, --dir <path>`	Target directory (default: `./choochoo/docs`)
`-f, --force`	Overwrite existing directory without prompting
`-y, --yes`	Skip all prompts, use defaults

The command auto-detects your git root and offers to scaffold there. See Project Structure for what gets created.

Validation

`validate`

Validate YAML and JSON files against ODPS, ODCS, OpenLineage, or AI System Card schemas.

choochoo validate <files|directories...> [options]
choochoo <files...>   # shorthand — routes to validate

Flag	Description
`-s, --schema <type>`	Force a schema type: `odps`, `odcs`, `openlineage`, `ai-system`
`-q, --quiet`	JSON output only, no status messages

How it works:

Accepts files or directories. Directories are searched recursively for .json, .yaml, and .yml files.
Auto-detects schema type from file content when --schema is not specified.
Outputs JSON results to stdout with per-file validation errors.
Prints a human-readable summary to stderr.
Exit code 0 if all files are valid, 1 if any are invalid.

Detection rules:

Schema	Detected when
ODPS (Data Product)	`kind === "DataProduct"`
ODCS (Data Contract)	`kind === "DataContract"`
AI System Card	`metadata.ai_system_name` exists
OpenLineage	`producer` string + one of `run`, `job`, `dataset`

Example output (--quiet):

{
  "results": [
    {
      "file": "contract.yaml",
      "valid": false,
      "schemaType": "odcs",
      "errors": [
        { "path": "/info", "message": "must have required property 'version'", "keyword": "required" }
      ]
    }
  ],
  "summary": { "total": 1, "valid": 0, "invalid": 1 }
}

Agent traces

`trace record`

Record a trace of who changed a file and how.

choochoo trace record [options]

Flag	Description
`-t, --type <type>`	(required) Contributor type: `human`, `ai`, `mixed`, `unknown`
`-f, --file <path>`	(required) Path to the file that was modified
`-m, --model <id>`	Model ID (e.g. `anthropic/claude-3-opus`)
`-x, --transcript <url>`	URL or path to conversation transcript
`-d, --metadata <json>`	Additional metadata as a JSON string
`-r, --range <start-end>`	Line range (e.g. `10-25`). Can be specified multiple times

Traces are appended to .choochoo/traces.ndjson (newline-delimited JSON).

`trace list`

List all recorded traces.

choochoo trace list [--json]

`trace show`

Show full details for a specific trace.

choochoo trace show <id>

`trace hooks scan`

Detect coding agents installed on your machine.

choochoo trace hooks scan [--json]

Scans for:

Claude Code (~/.claude/)
OpenCode (~/.opencode/)
Gemini CLI (~/.gemini/)
Codex (~/.codex/) — detected but hooks not yet supported

`trace hooks install`

Install ChooChoo trace hooks into detected agent config files.

choochoo trace hooks install [options]

Flag	Description
`--dry-run`	Preview changes without writing
`--no-create`	Skip creating new config files if missing
`--json`	Output results as JSON

For each agent, this adds hooks that call choochoo trace record on relevant events (session start/end, file edits, tool use).

Documentation

`tui`

Launch the interactive terminal UI for browsing agent traces, documentation, and schemas.

choochoo tui [--dir <path>]

Uses keyboard navigation with three tabs. See the TUI guide for details.

`web`

Start a local documentation server (Fumadocs).

choochoo web [options]

Flag	Description
`-d, --dir <path>`	Content directory (default: `./choochoo/docs`)
`-p, --port <number>`	Port (default: `3815`)
`-o, --open` / `--no-open`	Open browser automatically (default: `true`)

`map`

Render mermaid diagrams from markdown files as ASCII art in the terminal.

choochoo map <files|directories...> [options]

Flag	Description
`-q, --quiet`	Suppress file names and status messages
`-u, --unicode`	Use Unicode box-drawing characters

Recursively finds .md and .mdx files, extracts mermaid code blocks, and renders them.

Authentication

Authenticate with ChooChoo cloud services via OAuth device flow.

choochoo auth login [--no-browser]

Opens your browser to complete authentication. Token is saved locally and expires after 90 days.

`auth logout`

Sign out and revoke your token.

choochoo auth logout

`auth status`

Show current authentication state, including email, name, and token expiry.

choochoo auth status

`auth whoami`

Print your authenticated email. Exits with code 1 if not logged in.

choochoo auth whoami

Planned commands

The following commands appear in the broader ChooChoo design but are not yet implemented:

Command	Purpose
`choochoo product list\|create\|show`	Manage Data Products (ODPS)
`choochoo contract list\|create\|diff`	Manage Data Contracts (ODCS)
`choochoo agent list\|register\|audit`	Manage the agent registry
`choochoo governance submit\|approve\|reject\|risk-score`	Governance workflows and risk scoring
`choochoo lineage show`	Query the dependency graph
`choochoo compliance-report`	Generate compliance reports

See the Roadmap for planned timelines.

CLI Reference