Doctor · CLI

CLI reference

One umbrella command, specline, with three subcommands. doctor validates; rules and spec are self-describing and need no repo.

usage

specline doctor [PATH] [--mode author|gate] [--format json|human]
                       [--changed <file>...] [--now <iso-date>] [--tier 0|1|2]
specline rules  [--format json|markdown]
specline spec

specline doctor

Walks docs/ beneath PATH (default .), runs the tier's rules, and emits findings. JSON is the source of truth; human is a projection of it.

Flag	Meaning
--mode	`gate` (default) is strict; `author` reports missing required elements as `distance_to_ratifiable` (info) instead of errors — for shaping in progress.
--format	`human` (default at a terminal) or `json` (agents, CI).
--changed	Repo-relative paths you touched. Spec-scoped findings error only for specs in this set; otherwise they warn (quarantine).
--now	Reference ISO date for time-dependent checks. doctor never reads the wall clock — determinism.
--tier	Override the repo's declared tier (0, 1, 2) for testing.

Exit codes

Code	Means
0	No error-severity findings (warnings allowed).
1	At least one error. CI gates on this; agents parse the findings. The two never disagree.
2	Usage error (bad flag, no `docs/` found).
3	Internal error — to stderr, never as malformed stdout.

Output contract

specline doctor . --format json


  "tool_version": "0.1.0",
  "canon": "2.3.0-draft",
  "mode": "gate",
  "summary":  "errors": 0, "warnings": 1, "info": 0 ,
  "findings": [ /* rule_id, severity, scope, file, line, message, fix_hint */ ]

Output is deterministic — findings sort by file, then line (null first), then rule_id. Two runs on the same input and --now are byte-identical.

specline rules

Prints the full rule catalog — every rule_id with its severity, scope, tier, and downgradable flag — as --format markdown (default) or json. Needs no repo.

specline spec

Prints the pinned canon to stdout — for injecting Specline into an agent's context. Needs no repo. (The web twin is /spec.md.)