CLI reference

One binary, seven commands:

kronika init [--docs <path>] [--source <path>] [--replace]
kronika gui [--repo <path>] [--port <n>]
kronika sources [options]
kronika check --base <ref> [options]
kronika write [options]
kronika sync [options]
kronika onboarding [--advance | --skip | --reset | --status] [--json]

kronika with no arguments, help, -h, or --help prints usage. An unknown command or option, invalid value, or missing required argument prints kronika: <message> and help on stderr with exit status 2. Operational failures and blocker findings use status 1; see the runbook.

init, gui, sources, and onboarding need no Brama configuration. Model commands require BRAMA_URL and BRAMA_API_KEY_ROLE, a credential role reference rather than a secret. See configuration for resolution and signing.

Options

One parser serves all commands; flags irrelevant to a command are accepted but unused.

Numeric flags must be positive integers (<flag> must be a positive integer); a value-taking flag without a value is <flag> requires a value.

kronika init

Adopts the repository's existing Markdown into schema-version-1 kronika.sync.json. Default document selections are an existing README.md and every Markdown file beneath docs/; repeat --docs to choose exact files or directories. Every document receives the repeated --source paths, or . when none are supplied. The operation validates the entire selection before one atomic manifest write and never changes a document, invokes Brama, generates prose, or executes a repository command.

Stdout is JSON with status, imported, unchanged, conflicting, and rejected. An identical manifest is unchanged. A different existing manifest is a conflict and remains byte-for-byte intact unless --replace is explicit. Missing, escaping, symbolic-link, and non-Markdown selections are rejected before mutation. The manifest is the exact file consumed later by kronika sync.

kronika gui

Hosts the installed graphical importer on the IPv4 loopback address and prints its exact per-session URL without opening a browser. The repository is fixed by --repo; the form exposes document and evidence selections, manifest destination, standing instruction, and explicit conflict replacement. Submission calls the same exported initializeDocumentationWorkspace function as init, then reads the accepted manifest back for display. It does not call Brama, generate or alter a document, execute repository commands, deploy, or run validation.

kronika sources

Prints the safe source manifest without calling Brama:

{
  "repo": "...",
  "output": "README.md",
  "totalBytes": 12345,
  "sources": [{ "path": "src/cli.ts", "bytes": 13300 }],
  "skipped": [{ "path": ".env", "reason": "credential or generated lock file" }]
}

The collection's shape, lifecycle, and refusal sentences are in concepts/source-collection; the full selection and exclusion rules in sources. Exit 0 unless selection itself fails (source outside the repository, symbolic link, missing path).

kronika check

Audits one exact Git change against current documentation. --base is required; --base and --head are resolved to commit SHAs (git rev-parse --verify <ref>^{commit}) before the model call. The diff is taken with Git's own context and --find-renames over base...head; a diff larger than a stated --max-diff-bytes is refused with an error rather than audited truncated. The model must answer with a strict JSON verdict; a malformed verdict, or a passed value that contradicts its own blocker findings, is an error.

Text output is Kronika documentation check: PASSED or BLOCKED, the summary, and one line per finding. --json emits:

{
  "passed": false,
  "summary": "...",
  "findings": [
    {
      "severity": "blocker",
      "code": "stable-kebab-case-code",
      "document": "docs/cli.md",
      "sourcePaths": ["src/cli.ts"],
      "message": "...",
      "requiredChange": "..."
    }
  ],
  "model": "...",
  "baseSha": "...",
  "headSha": "...",
  "changedPaths": ["src/cli.ts"],
  "diffBytes": 4213,
  "sourceCount": 12,
  "skipped": []
}

Exit 0 when the audit passes (no blockers); exit 1 when it reports a blocker or fails — the gate never fails open. Warnings never block. The audit contract itself — "never require churn merely because source changed" — is enforced by the system prompt in src/docs/checker.ts; the verdict and finding vocabulary are concepts/check, concepts/audit, concepts/finding, and concepts/blocker-vs-warning. A blocked and a passing run, captured end to end, are in walkthrough-check.

kronika write

Generates one complete Markdown document through Brama from the selected sources and --instruction. Without --apply it prints the candidate to stdout and changes no file. With --apply it atomically replaces --output: the content is written to a temporary file beside the target and renamed into place, preserving the existing file mode. The output path must stay inside the repository. Model output is normalized — a surrounding Markdown code fence is stripped, empty content or content containing NUL is rejected — and always ends with a newline.

--json emits outputPath, applied, model, sourceCount, skipped, and, when not applied, the full content. The applied confirmation line is Wrote <path> from <n> source files via Brama.

kronika sync

Reconciles every document declared in the sync manifest with the repository: audits drifted ones, rewrites only audited defects, and records the reconciled commit. The full state machine is the sync loop.

Text output is one header line, Kronika sync at <sha12> (plus (dry run)), then one line per document: its action (baseline, current, advanced, checked-current, rewritten, failed) and detail. --json emits headSha, dryRun, committed, stateWritten, and the full outcomes array with changed paths and findings.

With --commit (and not --dry-run), sync stages the rewritten documents plus the state file and commits with the message kronika sync: reconcile <files> — or kronika sync: advance documentation baselines when only baselines moved. --push then runs git push. Exit 0 when every document reconciled; exit 1 when any outcome is failed.

One observed consequence of --commit: the sync commit itself moves HEAD past the recorded baselines, so the next tick reports advanced (a free baseline move over the sync commit), not current. Every action of the state machine, with output captured tick by tick, is in walkthrough-sync-cycle.