CLI, Runtime, and recovery

Use chat and role skills for guided work. Use Runtime or a CLI when the operation needs a stable schema, a preview, a confirmation gate, or machine-readable evidence.

Choose the current interface

Claude Desktop users invoke named role Skills and Runtime tools. Start with installation, the prompt library, and Runtime tools. Claude Code users should start with the distinct CLI setup; loading a role plugin, connecting Runtime and supplying code/product paths are separate checks.

Advanced CLI reference — source-version boundary

The recipes below span Core/Runtime CLI and separate role source executables. The current role Skills ZIPs do not contain the source executables. The source-tool flags shown here were checked against the split BA, Architect and Developer source snapshots audited on 2026-09-23; installed Runtime and vendored Core may have different revisions. Check your pinned release and run read-only status before automation. The source workflow needs explicit paths for both repositories; Runtime looks only in its selected local root.

Shared praxis CLI

Global options are --json, --quiet, --verbose, --help, and --version. The parser also accepts --dry-run. Prefer --json in automation; it emits the same envelope used by Runtime.

Domain	Commands	Behavior
Diagnostics	praxis doctor, praxis project status	Repository, configuration, Jira presence, Quality, and shell checks
Bootstrap	praxis project init --infer	Preview a minimal .project; add --confirm YES to write
Jira	praxis jira smoke, discover, epic, status	Connectivity, semantic discovery, and read-only issue hydration
BA	praxis ba status, preview, apply	Preview/apply BA mutations for an epic
Architect	praxis architect status, preview, apply	Preview/apply bounded Work Packages
Work packages	praxis work-package list, show, status	Resolve local IDs or Jira keys
Developer	praxis developer status, claim, release, complete	Claim lifecycle and promotion to QA
Quality	praxis quality status, ensure, review, report	Private Runtime and verification operations

Examples:

praxis doctor --repo . --json
praxis ba preview --epic PRX-1 --repo . --json
praxis ba apply --epic PRX-1 --confirm YES --fingerprint <preview-fingerprint> --json
praxis architect preview --epic PRX-1 --wp WP-20260914-002 --json
praxis developer status --wp WP-20260914-002 --json

Historical CLI edge cases in the earlier source snapshot

developer claim does not add the confirmation guard that Runtime adds. quality status can ensure the private local service. quality report currently dispatches the same operation as review. Use Runtime for human-facing mutations, or inspect the CLI preview and scope before execution.

Exit codes

Code	Meaning
0	Success
2	Usage or configuration error
3	Confirmation required
4	Blocked by a lifecycle gate
5	External service failure
6	Conflict or concurrency failure
7	Local execution unavailable
8	Validation failure

Current Runtime MCP tools

Use the current tool reference for the complete tool catalog, including Developer recovery, Git Delivery, and Quality Apply. Current Quality status is read-only. Ensure starts the service; Review executes supported configured checks and persists evidence without Jira writes or confirmation. Quality Apply is a separate approved mutation bound to its preview fingerprint.

Developer complete records evidence and leaves Jira In Progress. Quality operations explain review, Apply, canonical state, and partial retries for authorized teams. Git Delivery covers separately approved remote publication.

BA canon CLI

praxis-ba operates on a canon root. It uses exit 0 for success, 1 for hard failure, and 2 for advisory status.

vision confirm
cr confirm
cr realize
epic add
req edit
req retire
wp prepare
wp approve-plan
wp abandon
accept
bug capture
bug resolve
code-surface-scan
onboard-context
id next
status
goals status
check-goals
one-pager
rules-lint
render
export
migrate
migrate-v3
validate
fmt

Core forms:

praxis-ba validate --repo <canon-root>
praxis-ba id next --repo <canon-root> --scope cr
praxis-ba vision confirm --repo <canon-root> --by <name> --date <date>
praxis-ba cr confirm --repo <canon-root> --cr CR-001 \
  --entry requirement --impacts-file <impact.json>
praxis-ba wp approve-plan --repo <canon-root> --wp <WP-ID> \
  --plan wp/<WP-ID>/plan.md --json
praxis-ba accept --repo <canon-root> --wp <WP-ID> \
  --evidence <evidence-file> --by <name> --date <date>

cr capture, req add, and wp author are retired because skills mint IDs and write templates. baseline is intentionally rejected: only accept may create a baseline.

Architect tools

The governance executable supports these verbs:

classify-error-cost     record-council          assert-record-decision
write-platform-contract list-platform-contracts detect-missing-contracts
build-plan              submit-deviation        decide-deviation
conformance             intake-audit            context-map
divergence-points       alternatives            lens-review
record-decision         nfr-budget

Each form accepts the input/output flags shown by the release's help. Two package boundary tools are especially useful:

node <architect-source>/plugins/architect/tools/build-architecture-package.mjs \
  --ba-handoff <product-path>/wp/WP-20260914-002/handoffs/ba-architect.handoff.json \
  --change-spec <change-spec.json> --canon <product-path> \
  --out <product-path>/design --product <code-path>

node <architect-source>/plugins/architect/tools/emit-developer-handoff.mjs \
  --ba-handoff <product-path>/wp/WP-20260914-002/handoffs/ba-architect.handoff.json \
  --design-dir <product-path>/design/WP-20260914-002 --product <code-path>

detect-missing-contracts fails when required contracts are absent. A deviation decision verifies that an existing ADR was not mutated.

Developer tools

developer-governance.mjs provides:

research               notes                  web-research
scale                  preview                plan
assert-planning        assert-implement       execution-init
run-phase              caveman                deviation-gate
repair                 mr-prepare             mr-preview-remote
web-research-execute   stale-branches

The implementation path is explicit:

node <developer-source>/plugins/developer/tools/accept-work-package.mjs \
  --arch-handoff <product-path>/design/WP-20260914-002/architect-developer.handoff.json \
  --design-dir <product-path>/design/WP-20260914-002

node <developer-source>/plugins/developer/tools/run-work-package.mjs \
  --arch-handoff <product-path>/design/WP-20260914-002/architect-developer.handoff.json \
  --design-dir <product-path>/design/WP-20260914-002 \
  --product <code-path>

# After reviewing the generated plan, repeat the runner with --approve.
node <developer-source>/plugins/developer/tools/final-arbiter.mjs --cwd <code-path>

Without --approve, the source runner prepares the plan and stops before implementation. Its --design-dir may be outside --product: it writes dev/ journals and Quality handoff under that design directory while changing code/tests under --product. Review and stage both repositories separately. Missing or stale Architect references block acceptance; return to Architect instead of reconstructing design from a ticket. The governance MR source tool previews only. Current Runtime Git Delivery separately supports approved commit, push and PR/MR creation.

Knowledge CLI

Applicable rules are selected by role, stage, product, and service:

praxis-knowledge slice --root <knowledge-root> --role developer \
  --stage implement --product <product-id> --service <service-id>
praxis-knowledge precedent --path <precedent.md>
praxis-knowledge finding list --store <findings.json>

The finding lifecycle also supports propose, successful-override, accept, and reject. A proposed rule does not become governing knowledge until it is accepted.

Recovery playbook

1. Run praxis doctor --repo . --json.
2. Run the role's status operation.
3. Invoke the role's resume skill.
4. Inspect the persisted artifact or journal named by the result.
5. Continue at the next incomplete gate.

For a repeated Developer failure, keep the same fingerprint in repair-loop. Three identical failures plus fresh attempts trigger escalation instead of infinite retry. For BA acceptance, a pending marker identifies a transaction that must be resumed. For Jira writes, the write journal records planned, creating, created, verified, and committed states so retries can remain idempotent.

Automation rules

• Parse --json; do not scrape prose.
• Treat an operation that returns findings as completed even when the verdict is fail.
• Bind apply to its preview fingerprint.
• Record the exact command, commit, and evidence path.
• Never place a secret in an argument, transcript, artifact, or .project.
• Prefer status and preview calls before retrying a write.