sdd-cli

The sdd CLI — Interface Discipline

The sdd binary is the write path for SDD artifacts and the deterministic half of validation. Artifacts are compiled documents: create and modify them through the binary, never by hand-editing frontmatter or evidence sections — a hand edit bypasses schema compilation, digest tracking, and the refusal gates the workflow depends on.

Run sdd help for the authoritative usage; sdd schema list / sdd schema show <type> for the artifact contracts. This skill carries the discipline and the task→command map, not every flag.

Start here

Run sdd doctor once when you begin using sdd in a project. It reports the binary in use, the resolved planning root, and the embedded schema set, and it regenerates hooks.json when that file is absent or does not match this plugin version's hook set.

That last part is why it matters: hooks.json is generated per platform, so a plugin upgrade leaves the previous version's file in place. The events it declares keep firing, which means a newly added event silently never runs and nothing looks wrong. doctor is the only thing that compares. Pass --check to report without repairing.

Contracts (apply to every subcommand)

• Exit codes: 0 success · 1 refused mutation or authoritative findings · 2 malformed invocation or the operation could not run. Exit 1 means the gate is doing its job — fix the input or complete the missing prerequisite; never work around it by editing the file directly.
• Severities follow the compiler model. Only error (and operational, meaning a check could not run) makes a root or ledger invalid and sets a failing exit status. warning is a real defect that cannot threaten correctness — including one inherited history forbids repairing; candidate is a signal for a human to judge; waived is a finding someone explicitly excepted. All three are reported and none gates. A clean run with non-blocking findings still says Valid, with the count — treat "no findings" and "findings, none blocking" as different states.
• Machine reads: prefer --json over parsing rendered markdown.
• Preview before mutate: --dry-run and --diff are available on the writing commands; use them when the change is non-obvious.
• Concurrent-edit safety: sdd show reports a content digest; pass it back via --expect DIGEST on apply/section set so the write is refused if the artifact changed underneath you.
• stdin writers: apply reads a full Markdown proposal on stdin; section set reads one section body on stdin and leaves everything else byte-identical (aside from updated).