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.

---

Context

context generate

Scan the project and generate an AGENTS.md file that gives AI agents a pre-compiled map of the codebase.

choochoo context generate [options]

Flag	Description
-o, --output <path>	Output file path (default: AGENTS.md in project root)
-d, --dir <path>	Project root directory to scan (default: git root or cwd)
--stdout	Print to stdout instead of writing a file
-f, --force	Overwrite existing AGENTS.md without prompting

What it generates:

• Project metadata (language, package manager, frameworks)
• Directory tree (depth 3, excludes node_modules, .git, etc.)
• Governance artifacts (detected ODPS, ODCS, OpenLineage, AI System Card files)
• Configured agents (Claude Code, Cursor, OpenCode, Gemini CLI, Codex)
• Documentation files (README, CHANGELOG, AGENTS.md, etc.)
• ChooChoo configuration status

context show

Display a summary of the project context without generating a file.

choochoo context show [options]

Flag	Description
-d, --dir <path>	Project root directory to scan
--json	Output as JSON

---

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.jsonl (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 (agent traces, documentation, schemas). Press ? inside the TUI for the full keyboard cheatsheet.

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

auth login

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.

Related

• Error Messages — Catalog of error codes with troubleshooting guidance.
• CI/CD Integration — Add choochoo validate to your pipeline.
• Configuration — Project-local files, user data, and environment variables.
• Agent Trace — Auto-install hooks and inspect recorded traces.