CLI reference
One umbrella command, specline, with six subcommands. check is the checker (and the default) — point it at a repo. rules and spec describe themselves and need no repo at all. Specline runs in one mode: it reports every finding and exits nonzero when any of them is an error.
specline check [PATH] [--format json|human]
[--changed <file>...] [--modified <file>...] [--now <iso-date>]
specline rules [PATH] [--format json|markdown]
specline spec [PATH]
specline init [PATH] [--decider <name>]
[--github-action | --no-github-action] [--check] [--yes]
specline sync [PATH] [--check]
specline upgrade [PATH] [--check]specline check
This is where the checking happens. Specline walks docs/ beneath PATH (default .), runs Parts 1 and 2's rules (plus Part 3's, experimental, if specline.yml sets unattended: true), and emits findings. JSON is the source of truth; the human output is just a view onto it.
| Flag | Meaning |
|---|---|
| --format | human (default at a terminal) or json (agents, CI). |
| --changed | Repo-relative paths you touched. Spec-scoped integrity findings error only for specs in this set; otherwise they warn (quarantine). |
| --modified | Repo-relative modified or removed paths for archive immutability. New archive files are graduation and should not be included. |
| --now | Reference ISO date for time-dependent checks. Specline never reads the wall clock — determinism. |
Exit codes
| Code | Means |
|---|---|
| 0 | No error-severity findings (warnings allowed); or a clean --check on init/sync/upgrade. |
| 1 | At least one error, or a stale --check. 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
{ "tool_version": "0.1.0", "canon": "3.1.0", "unattended": false, "summary": { "errors": 0, "warnings": 1, "info": 0 }, "findings": [ /* rule_id, severity, scope, file, line, message, fix_hint */ ] }
The output never surprises you. Findings sort by file, then line (null first), then rule_id — so two runs on the same input and the same --now come out byte-identical.
specline rules
Prints the full rule catalog — every rule_id with its severity and scope — as --format markdown (default) or json. Reads PATH's specline.yml for the unattended switch (default .); with it off, Part 3's rules are neither listed nor served.
specline spec
Prints the pinned canon to stdout, sliced at Part 3 unless PATH's specline.yml sets unattended: true. Use it to drop Specline straight into an agent's context. (The web twin is /spec.md.)
specline init / sync / upgrade
init creates the starting documentation directories (drafts/, specs/, knowledge/, archive/, conventions/, decisions/, strategy/, technical/), authored starters, specline.yml, and an optional GitHub Action. Use --yes for noninteractive defaults. sync refreshes recognized generated artifacts in existing directories. upgrade updates the canon pin and refreshes generated artifacts — and maps a legacy tier: 2 to unattended: true, dropping tier: 0|1. Existing authored file contents are preserved, but spec paths can change.
upgrade moves each entire docs/specs/<slug>/ folder carrying status: draft or status: ratified into docs/drafts/<slug>/, including auxiliary files. Specs carrying status: building or no status stay put. This is a folder migration, not necessarily a pin-only change: each legacy draft requires a folder move. Preview with specline upgrade PATH --check, then inspect an actual upgrade in a disposable copy before adoption, including references to old paths. Editing the pin alone does not perform the migration.
All three accept --check: preview without writes, returning 1 when changes are needed and 0 when current. doctor remains a compatibility alias for check.