doctor_frankentui commands

doctor_frankentui is a single binary with six subcommands. Each command has a canonical name and a legacy alias; both are accepted. All commands accept --machine {auto, human, json} for CI output.

Source: crates/doctor_frankentui/src/cli.rs.

Invocation

# Standard invocation via cargo
cargo run -p doctor_frankentui -- <subcommand> [args…]
 
# Or the installed binary
doctor_frankentui <subcommand> [args…]
 
# Machine-readable output for CI
doctor_frankentui --machine json <subcommand> [args…]

Subcommand topology

doctor_frankentui
├── replay     (alias: capture)  — single-profile replay
├── seed-demo                    — MCP bootstrap + demo seeding
├── migrate    (alias: suite)    — profile-matrix replay
├── certify    (alias: doctor)   — environment smoke test
├── report                       — HTML/JSON/plaintext synthesis
├── plan       (alias: import)   — import-intake planning
└── list-profiles                — print built-in profile names

replay (alias: capture)

Full replay/capture workflow for a single profile. Orchestrates seed-demo bootstrap if requested, spawns a child replay through a PTY or VHS, and writes a RunMeta + an evidence_ledger.jsonl under the run root.

doctor_frankentui replay \
    --profile modern \
    --run-root /tmp/doctor_frankentui/replay \
    --run-name run_001

Primary artifacts: RunMeta JSON, evidence_ledger.jsonl, per-capture tape/VHS files.

Prerequisites: cargo. Optional: tmux for observed-mode captures.

seed-demo

MCP bootstrap and deterministic demo seeding. Health-checks the endpoint, retries with bounded backoff, and writes a deterministic endpoint/project/agent summary.

doctor_frankentui seed-demo \
    --endpoint http://127.0.0.1:8787 \
    --run-root /tmp/doctor_frankentui/seed

Primary artifacts: optional RPC log file, deterministic endpoint summary.

Prerequisites: cargo, an MCP server reachable at the configured endpoint.

migrate (alias: suite)

Repeated replay runs across a profile matrix — the authoritative regression entry point. Synthesises a per-suite manifest with per-run trace IDs and a fallback index.

doctor_frankentui migrate \
    --profiles modern,xterm-256color,tmux,dumb \
    --run-root /tmp/doctor_frankentui/migrate

Primary artifacts: suite summary.json, per-run trace IDs, fallback index.

Prerequisites: cargo, python3 (for schema validation), sometimes tmux when a profile demands mux observation.

certify (alias: doctor)

Environment and capture-stack certification. Runs a minimal smoke capture, classifies degraded modes, optionally attaches a tmux fallback session. Produces a doctor_summary.json and, when --full is enabled, a complete capture-stack detail.

doctor_frankentui certify \
    --full \
    --run-root /tmp/doctor_frankentui/doctor \
    --capture-timeout-seconds 45 \
    --allow-degraded

DoctorArgs (selected fields):

Exit codes:

• 0 — healthy
• 30 — DEGRADED_CAPTURE_EXIT_CODE — ran, but the capture stack was degraded (e.g. no raw mode, mux-only). --allow-degraded collapses this to 0.
• non-zero (other) — hard failure (build failed, demo crashed, etc.)

Primary artifacts: doctor_summary.json with status, capture_stack_health, degraded_capture, degraded_reason, fallback_error, capture_smoke_detail, capture_smoke, app_smoke_summary, and (when observing) tmux_session + tmux_pane_capture + tmux_pane_log.

Prerequisites: cargo. Optional: tmux for observed-mode.

report

Post-processing over completed suite runs. Aggregates per-run outcomes with trace IDs, synthesises HTML, JSON, and plaintext reports.

doctor_frankentui report \
    --suite-root /tmp/doctor_frankentui/migrate \
    --output-dir /tmp/doctor_frankentui/report

Primary artifacts: report.html, report.json, report.txt.

Prerequisites: cargo. The suite root must already contain a completed migrate / suite run.

plan (alias: import)

Import-intake planning and snapshot materialisation. Mostly deterministic analysis — lower supervision value than the other commands, useful when preparing new fixtures for import into ftui-demo-showcase.

doctor_frankentui plan \
    --import-root ./incoming_fixtures \
    --output-dir /tmp/doctor_frankentui/plan

Prerequisites: cargo.

list-profiles

Print the built-in capture profile names. Useful before invoking migrate --profiles ….

doctor_frankentui list-profiles

Required toolchain pieces, by command

Machine mode

--machine json is mandatory in CI. It does three things:

1. Emits structured JSON on stdout instead of ANSI-coloured text.
2. Mirrors errors onto stderr as {"error": {...}} so pipelines can distinguish.
3. Suppresses progress spinners and TUI-like output that would interleave with the log stream.

doctor_frankentui --machine json certify > /tmp/result.json

Related