CLI Reference

This is the full searchable reference for the cruxible command line. Walkthroughs and agent recipes live elsewhere; this file is intentionally detailed so an agent can look up command names, flags, side effects, and failure modes without shelling out to --help first.

Runtime Model

• Use --server-url or --server-socket for daemon transport, and --instance-id or CLI context for daemon-backed instances.
• The CLI context commands remember transport and the active instance for shell users; MCP does not use CLI context.
• Commands that mutate governed state are blocked locally when the command requires a daemon surface.
• init --kit accepts standalone kits. Overlay kits are created with state create-overlay --kit.
• run rejects proposal workflows; use propose for workflows that return governed relationship proposals.
• explain and export edges are direct-local file/rendering utilities. Use receipts and list/query tools for daemon/MCP flows.

Global Options

Options on the cruxible root group itself. They precede the command name (cruxible --instance-id inst_... list entities) and apply to every subcommand.

Options And Arguments:

Name	Required	Default	Type	Description
--version	no	False	boolean	Show the version and exit.
--server-url	no	``	text	Remote Cruxible server base URL.
--server-socket	no	``	text	Local Cruxible server Unix socket path.
--instance-id	no	``	text	Opaque server-mode instance ID. Defaults to remembered CLI context.
--json-compact	no	``	boolean	Emit all CLI JSON as compact single-line output (also CRUXIBLE_JSON_COMPACT=1).

Command Word Order

Operations on a specific named resource instance are noun-first: cruxible entity add, cruxible entity update, cruxible relationship add, and cruxible relationship update. Cross-resource collection and inspection commands remain top-level where the target is not a single CRUD-style resource, for example list, inspect, and sample.

There is no hard-delete/remove command. Cruxible state is receipted and append-oriented; retire entities by setting ontology lifecycle fields such as status=closed or status=superseded, and reject relationship assertions with the feedback/review surfaces.

Direct Write Shorthand

Usage:

cruxible entity add ENTITY_TYPE ENTITY_ID [--set FIELD=VALUE] [--set-json FIELD=JSON] [--dry-run] [--json]
cruxible entity update ENTITY_TYPE ENTITY_ID --set FIELD=VALUE [--set-json FIELD=JSON] [--dry-run] [--json]
cruxible relationship add REL_TYPE FROM_TYPE FROM_ID TO_TYPE TO_ID [--set FIELD=VALUE] [--set-json FIELD=JSON] [--dry-run] [--json]
cruxible relationship update REL_TYPE FROM_TYPE FROM_ID TO_TYPE TO_ID [--set FIELD=VALUE] [--set-json FIELD=JSON] [--dry-run] [--json]

Purpose: Ergonomic CLI shorthand for creating and updating entities and relationships without hand-authoring a direct-write payload file.

Field Assignment: - --set FIELD=VALUE stores VALUE as a string. Values such as NO, no, 1.20, 0755, and null are not coerced. - --set-json FIELD=JSON stores an explicitly typed JSON value. - --props JSON remains accepted on noun write commands for compatibility. - Duplicate fields, blank field names, and malformed assignments are rejected.

Relationship Evidence Options: - --evidence-ref JSON - --source-evidence JSON - --citation-handle TOKEN - --evidence-rationale TEXT

Output And Side Effects: - Uses the same guarded direct-write path as batch-direct-write, with the same dry-run behavior, receipts, mutation guards, and group-interaction notices. - entity add and relationship add fail if the target already exists. - entity update and relationship update fail if the target does not exist. - --json emits the same BatchDirectWriteResult envelope as batch-direct-write. - Actor attribution remains credential-derived when daemon auth is enabled.

Examples:

cruxible entity add WorkItem wi-example --set title="Add write verbs" --set status=planned
cruxible entity update WorkItem wi-example --set status=closed
cruxible relationship add work_item_part_of_work_item WorkItem wi-child WorkItem wi-parent --set composition_basis="Same ergonomics slice"
cruxible relationship update work_item_part_of_work_item WorkItem wi-child WorkItem wi-parent --set composition_basis="Refined after review"

cruxible config

Usage: cruxible config [OPTIONS]

Purpose: Edit, validate, and render the active config.

Subcommands:

• cruxible config reload - Validate the active config or repoint the instance to a new config file.
• cruxible config status - Compare authored config layers with the active materialization.
• cruxible config views - Render canonical Mermaid/Markdown views for a Cruxible config.
• cruxible config expand - Expand a compact authoring config to the explicit engine config.
• cruxible config add-constraint - Add a constraint rule to the config.
• cruxible config add-decision-policy - Add a decision policy to the config.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, or rendered file output depending on the subcommand.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible config expand

Usage: cruxible config expand [OPTIONS]

Purpose: Expand a compact authoring config to the explicit engine config. The compact form is the single source of truth; the loader expands it on load, so the explicit output is for inspection/review (e.g. diffing the resolved graph), not a committed artifact.

Options And Arguments:

Name	Required	Default	Type	Description
--in	yes	``	file	Path to the compact authoring YAML to expand.
--out	no	stdout	file	Write the expanded explicit YAML here.
--validate / --no-validate	no	validate	flag	Validate the expanded config as a CoreConfig before writing.

Output And Side Effects: - Pure transform: reads the compact YAML and writes the expanded explicit YAML to --out (or stdout). No instance, daemon, or graph state is touched.

Common Errors: - Malformed compact grammar (raises a compact-expansion error naming the construct). - The expanded config fails CoreConfig validation (unless --no-validate).

cruxible config add-constraint

Usage: cruxible config add-constraint [OPTIONS]

Purpose: Add a constraint rule to the config.

Options And Arguments:

Name	Required	Default	Type	Description
--name	yes	Sentinel.UNSET	text	Constraint name.
--rule	yes	Sentinel.UNSET	text	Constraint rule expression.
--severity	no	warning	choice	Severity level (default: warning).
--description	no	``	text	Optional description.

Output And Side Effects: - Config mutation. Adds a constraint rule to the active config and reports the constraint name plus any validation warnings. Server-mode only.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations. - Local mutation disabled when not server-backed; run against a server-mode instance.

cruxible config add-decision-policy

Usage: cruxible config add-decision-policy [OPTIONS]

Purpose: Add a decision policy to the config.

Options And Arguments:

Name	Required	Default	Type	Description
--name	yes	Sentinel.UNSET	text	Decision policy name.
--applies-to	yes	Sentinel.UNSET	choice	Policy application surface.
--relationship	yes	Sentinel.UNSET	text	Relationship type.
--effect	yes	Sentinel.UNSET	choice	Policy effect.
--query-name	no	``	text	Named query for query policies.
--workflow-name	no	``	text	Workflow name for workflow policies.
--match	no	{}	text	JSON object for exact-match selectors.
--description	no	``	text	Optional description.
--rationale	no	``	text	Policy rationale.
--expires-at	no	``	text	Optional ISO timestamp/date.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible entity

Usage: cruxible entity [OPTIONS]

Purpose: Entity reads and writes.

Subcommands:

• cruxible entity add - Create one entity.
• cruxible entity get - Look up a specific entity by type and ID.
• cruxible entity history - Inspect receipt-derived entity change history for one entity type or entity.
• cruxible entity inspect - Inspect an entity and its immediate neighbors.
• cruxible entity retire - Retire an entity without cascading attached edges.
• cruxible entity supersede - Supersede an entity with an existing live same-type successor.
• cruxible entity update - Update one existing entity.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible entity add

Usage: cruxible entity add [OPTIONS] [ENTITY_TYPE] [ENTITY_ID]

Purpose: Create one entity using JSON properties or FIELD=VALUE assignments.

Options And Arguments:

Name	Required	Default	Type	Description
ENTITY_TYPE	no	``	argument	Entity type.
ENTITY_ID	no	``	argument	Entity ID.
--type	no	``	text	Entity type, for compatibility with older noun command usage.
--id	no	``	text	Entity ID, for compatibility with older noun command usage.
--props	no	``	text	JSON object of properties.
--set	no	``	text	String property assignment FIELD=VALUE. Repeat for multiple properties.
--set-json	no	``	text	Typed JSON property assignment FIELD=JSON. Repeat for multiple properties.
--lifecycle-status	no	``	choice	Typed entity lifecycle status. Only live is writable here; the terminal statuses retired/superseded are refused on add/update — use cruxible entity supersede or cruxible entity retire.
--lifecycle-reason	no	``	text	Optional reason for the lifecycle status (requires --lifecycle-status).
--dry-run	no	False	boolean	Validate without mutating graph state.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Uses the same guarded direct-write path as batch-direct-write. - Fails if the entity already exists. - JSON output is a BatchDirectWriteResult.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible entity update

Usage: cruxible entity update [OPTIONS] [ENTITY_TYPE] [ENTITY_ID]

Purpose: Update one existing entity using JSON properties or FIELD=VALUE assignments.

Options And Arguments:

Name	Required	Default	Type	Description
ENTITY_TYPE	no	``	argument	Entity type.
ENTITY_ID	no	``	argument	Entity ID.
--type	no	``	text	Entity type, for compatibility with older noun command usage.
--id	no	``	text	Entity ID, for compatibility with older noun command usage.
--props	no	``	text	JSON object of properties.
--set	no	``	text	String property assignment FIELD=VALUE. Repeat for multiple properties.
--set-json	no	``	text	Typed JSON property assignment FIELD=JSON. Repeat for multiple properties.
--lifecycle-status	no	``	choice	Typed entity lifecycle status. Only live is writable here; the terminal statuses retired/superseded are refused on add/update — use cruxible entity supersede or cruxible entity retire.
--lifecycle-reason	no	``	text	Optional reason for the lifecycle status (requires --lifecycle-status).
--dry-run	no	False	boolean	Validate without mutating graph state.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Uses the same guarded direct-write path as batch-direct-write. - Fails if the entity does not already exist. - Requires at least one --props, --set, or --set-json property update. - JSON output is a BatchDirectWriteResult.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible entity supersede

Usage: cruxible entity supersede [OPTIONS] ENTITY_TYPE ENTITY_ID SUCCESSOR_ENTITY_TYPE SUCCESSOR_ENTITY_ID

Purpose: Settle an entity as superseded by an existing live same-type successor.

Options And Arguments:

Name	Required	Default	Type	Description
ENTITY_TYPE	yes	``	argument	Predecessor entity type.
ENTITY_ID	yes	``	argument	Predecessor entity ID.
SUCCESSOR_ENTITY_TYPE	yes	``	argument	Successor entity type; must equal the predecessor's type.
SUCCESSOR_ENTITY_ID	yes	``	argument	Successor entity ID; the successor must already exist and be live.
--reason	yes	Sentinel.UNSET	text	Required adjudication reason.
--evidence-ref	no	``	text	Optional evidence reference as a JSON object.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - A settled adjudication at GRAPH_WRITE, recorded in one mutation receipt with the subject, the transition, the reason, and the successor reference. - Writes typed supersession pointers in BOTH directions (successor.supersedes, predecessor.superseded_by), moves the predecessor's lifecycle.status to superseded, and stamps closed_at/closed_by. - Inbound edges do NOT migrate: a superseded entity's attached claims stay pointed at the predecessor. Re-pointing is the caller's job. - Refused when the successor is missing, not live, of a different type, is the subject itself, or already supersedes another entity; and when the predecessor is not live.

Common Errors: - Empty or missing --reason — a settled transition without a reason is refused. - Permission mode below GRAPH_WRITE. - Successor absent, not live, or already recorded as superseding something else.

cruxible entity retire

Usage: cruxible entity retire [OPTIONS] ENTITY_TYPE ENTITY_ID

Purpose: Settle an entity as retired, with no successor and no cascade.

Options And Arguments:

Name	Required	Default	Type	Description
ENTITY_TYPE	yes	``	argument	Entity type.
ENTITY_ID	yes	``	argument	Entity ID.
--reason	yes	Sentinel.UNSET	text	Required adjudication reason.
--evidence-ref	no	``	text	Optional evidence reference as a JSON object.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - A settled adjudication at GRAPH_WRITE, recorded in one mutation receipt. - Moves lifecycle.status to retired and stamps closed_at/closed_by. - Reports stranded_live_edge_count: still-live edges attached to the retired entity, which stay visible in edge-level reads but drop out of traversals. Cascade is deliberately not performed — re-pointing is the caller's job. - The retired entity_id is preserved, not freed: a later DIRECT add/update of that id is refused rather than minting a doppelganger with none of the original's history. Governed sources (workflow apply, group resolve) still reach the entity; reversing a retirement awaits the deferred reinstate verb.

Common Errors: - Empty or missing --reason. - Permission mode below GRAPH_WRITE. - The entity is not live (already retired or superseded).

cruxible entity get

Usage: cruxible entity get [OPTIONS]

Purpose: Look up a specific entity by type and ID.

Options And Arguments:

Name	Required	Default	Type	Description
--type	yes	Sentinel.UNSET	text	Entity type.
--id	yes	Sentinel.UNSET	text	Entity ID.
--profile	no	standard	choice	JSON output profile: compact (bounded identity cards with governance markers), standard (full shape), or full (reserved superset of standard).
--ws	no	False	boolean	Also capture this --json read into the agent-local working set (non-authoritative cache; see cruxible ws).
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event. - A by-id get is not subject to live-only lifecycle gating: it returns the entity even when its lifecycle.status is retired/superseded, and surfaces that status (in the Lifecycle table column and in the JSON metadata.lifecycle.status). This is the recovery/inspection path for an entity hidden from live query/list reads.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible entity history

Usage: cruxible entity history [OPTIONS]

Purpose: Inspect receipt-derived entity change history for one entity type or entity.

Noun-first read of an entity's history.

Options And Arguments:

Name	Required	Default	Type	Description
--type	yes	Sentinel.UNSET	text	Entity type.
--id	no	``	text	Optional entity ID.
--limit	no	50	integer range
--offset	no	0	integer range
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only. Shows property diffs recorded on mutation receipts for entity writes.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible entity inspect

Usage: cruxible entity inspect [OPTIONS]

Purpose: Inspect an entity and its bounded neighborhood.

Noun-first read of a single entity. Without neighborhood options this is the legacy single-hop neighbor read. Providing any of --depth, --target-type, --state, --projection, --max-nodes, --max-edges (or repeating --relationship) switches to the expanded bounded BFS read: nodes/edges grouped by depth with explicit budgets and visible truncation (truncated + truncation_reasons: node_budget/edge_budget/depth). Every node and edge keeps its lifecycle/review markers. By default every stored edge is returned (state=all, the inspection contract); an explicit --state filters like named-query traversal and the response reports edges_hidden_by_state — edges at the explored frontier that passed every other filter and were hidden by state alone (table output prints a pass --state all hint when the count is non-zero). --projection selects neighbor properties (the root keeps its full properties); --profile shapes metadata — the two compose. With --json the expanded shape is emitted; table output groups nodes by depth.

Options And Arguments:

Name	Required	Default	Type	Description
--type	yes	Sentinel.UNSET	text	Entity type.
--id	yes	Sentinel.UNSET	text	Entity ID.
--direction	no	both	choice	Neighbor traversal direction.
--relationship	no	``	text	Relationship type filter; repeatable (multiple values expand the read).
--limit	no	``	integer range	Max neighbors to show (legacy single-hop cap; maps to the node budget on expanded reads).
--depth	no	``	integer range	Hop horizon for the expanded read (1-4). Providing it (even --depth 1) opts into the expanded nodes/edges shape.
--target-type	no	``	text	Only expand into/return entities of these types (root exempt); repeatable.
--state	no	``	choice	Relationship visibility for the expanded read: all (default — every stored edge, the inspection contract), live, accepted, not-live, pending, reviewable — explicit states filter with identical semantics to named-query traversal.
--projection	no	``	text	Neighbor property names to keep (root keeps full properties); repeatable.
--max-nodes	no	``	integer range	Node budget for the expanded read (default 100, hard cap 500).
--max-edges	no	``	integer range	Edge budget for the expanded read (default 200, hard cap 1000).
--profile	no	standard	choice	JSON output profile: compact (bounded identity cards with governance markers), standard (full shape), or full (reserved superset of standard).
--continue	no	``	text	Continuation token from a previous budget-truncated expanded read; repeat the same structural options (entity, depth, direction, filters, state). Stale after any state mutation — restart the read.
--ws	no	False	boolean	Also capture this --json read into the agent-local working set (non-authoritative cache; see cruxible ws).
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event. - Expanded reads carry read_revision (the state freshness marker; receipts prove computation, never freshness) and, when truncated on a budget, a continuation_token — resume with --continue TOKEN and the same options. The resumed pages are disjoint and their union is exactly the untruncated result set. Depth-horizon truncation is not resumable (pass a larger --depth instead). Table output prints the resume hint on truncation.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Stale continuation token after a mutation, or a malformed token. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible relationship

Usage: cruxible relationship [OPTIONS]

Purpose: Relationship reads and writes.

Subcommands:

• cruxible relationship add - Create one relationship.
• cruxible relationship get - Look up a specific relationship by its endpoints and type.
• cruxible relationship lineage - Inspect a relationship's stored provenance lineage.
• cruxible relationship retract - Retract a claim without a successor.
• cruxible relationship supersede - Supersede a claim with an existing live same-type successor.
• cruxible relationship update - Update one existing relationship.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible relationship add

Usage: cruxible relationship add [OPTIONS] [RELATIONSHIP_TYPE] [FROM_TYPE] [FROM_ID] [TO_TYPE] [TO_ID]

Purpose: Create one relationship using JSON properties, FIELD=VALUE assignments, or evidence flags.

Options And Arguments:

Name	Required	Default	Type	Description
RELATIONSHIP_TYPE	no	``	argument	Relationship type.
FROM_TYPE	no	``	argument	Source entity type.
FROM_ID	no	``	argument	Source entity ID.
TO_TYPE	no	``	argument	Target entity type.
TO_ID	no	``	argument	Target entity ID.
--from-type	no	``	text	Source entity type, for compatibility with older noun command usage.
--from-id	no	``	text	Source entity ID, for compatibility with older noun command usage.
--relationship / --type	no	``	text	Relationship type, for compatibility with older noun command usage.
--to-type	no	``	text	Target entity type, for compatibility with older noun command usage.
--to-id	no	``	text	Target entity ID, for compatibility with older noun command usage.
--props	no	``	text	JSON object of edge properties.
--set	no	``	text	String relationship property assignment FIELD=VALUE.
--set-json	no	``	text	Typed JSON relationship property assignment FIELD=JSON.
--evidence-ref	no	``	text	JSON evidence ref object. Repeat to attach multiple refs.
--source-evidence	no	``	text	JSON source-evidence locator. Repeat to attach multiple locators.
--citation-handle	no	``	text	Server-minted, revision-pinned source-evidence handle. Repeat to attach multiple handles.
--evidence-rationale	no	``	text	Optional rationale for the attached relationship evidence.
--pending	no	False	boolean	Create the relationship as pending review instead of live state.
--lifecycle-status	no	``	choice	Typed edge lifecycle status. Only active/inactive are writable here; the terminal statuses retracted/superseded are refused on add/update — use cruxible relationship supersede or cruxible relationship retract. Sets only assertion.lifecycle; cannot approve/reject the edge.
--lifecycle-reason	no	``	text	Optional reason for the lifecycle status (requires --lifecycle-status).
--dry-run	no	False	boolean	Validate without mutating graph state.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Uses the same guarded direct-write path as batch-direct-write. - Fails if the relationship tuple already exists. - Evidence refs, source-evidence locators, and citation handles are persisted as the same canonical relationship evidence metadata. Direct adds are not group-reviewed accepted relationships; use group propose and group resolve --action approve when review/acceptance state matters. - JSON output is a BatchDirectWriteResult.

Example:

cruxible relationship add \
  roadmap_item_depends_on_roadmap_item \
  RoadmapItem ri-compact-workflow-trace-payloads \
  RoadmapItem ri-transactional-sqlite-state \
  --citation-handle cite1_4f8c3a1d87be76dd3260 \
  --evidence-rationale "Extracted from the P0 section."

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible relationship update

Usage: cruxible relationship update [OPTIONS] [RELATIONSHIP_TYPE] [FROM_TYPE] [FROM_ID] [TO_TYPE] [TO_ID]

Purpose: Update one existing relationship using JSON properties, FIELD=VALUE assignments, or evidence flags.

Options And Arguments:

Name	Required	Default	Type	Description
RELATIONSHIP_TYPE	no	``	argument	Relationship type.
FROM_TYPE	no	``	argument	Source entity type.
FROM_ID	no	``	argument	Source entity ID.
TO_TYPE	no	``	argument	Target entity type.
TO_ID	no	``	argument	Target entity ID.
--from-type	no	``	text	Source entity type, for compatibility with older noun command usage.
--from-id	no	``	text	Source entity ID, for compatibility with older noun command usage.
--relationship / --type	no	``	text	Relationship type, for compatibility with older noun command usage.
--to-type	no	``	text	Target entity type, for compatibility with older noun command usage.
--to-id	no	``	text	Target entity ID, for compatibility with older noun command usage.
--props	no	``	text	JSON object of edge properties.
--set	no	``	text	String relationship property assignment FIELD=VALUE.
--set-json	no	``	text	Typed JSON relationship property assignment FIELD=JSON.
--evidence-ref	no	``	text	JSON evidence ref object. Repeat to attach multiple refs.
--source-evidence	no	``	text	JSON source-evidence locator. Repeat to attach multiple locators.
--citation-handle	no	``	text	Server-minted, revision-pinned source-evidence handle. Repeat to attach multiple handles.
--evidence-rationale	no	``	text	Optional rationale for the attached relationship evidence.
--lifecycle-status	no	``	choice	Typed edge lifecycle status -- e.g. deactivate a live edge. Only active/inactive are writable here; the terminal statuses retracted/superseded are refused on add/update — use cruxible relationship supersede or cruxible relationship retract. Sets only assertion.lifecycle; cannot approve/reject the edge.
--lifecycle-reason	no	``	text	Optional reason for the lifecycle status (requires --lifecycle-status).
--dry-run	no	False	boolean	Validate without mutating graph state.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Uses the same guarded direct-write path as batch-direct-write. - Fails if the relationship tuple does not already exist. - Requires at least one property or evidence update. - JSON output is a BatchDirectWriteResult.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible relationship supersede

Usage: cruxible relationship supersede [OPTIONS] CLAIM_ID SUCCESSOR_CLAIM_ID

Purpose: Settle a claim as superseded by an existing live same-type claim.

Options And Arguments:

Name	Required	Default	Type	Description
CLAIM_ID	yes	``	argument	Predecessor claim ID.
SUCCESSOR_CLAIM_ID	yes	``	argument	Successor claim ID; must already exist, be live, and share the relationship type.
--reason	yes	Sentinel.UNSET	text	Required adjudication reason.
--evidence-ref	no	``	text	Optional evidence reference as a JSON object.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - A settled adjudication at GRAPH_WRITE, recorded in one mutation receipt with the subject, the transition, the reason, and the successor reference. - Writes typed claim_id supersession pointers in BOTH directions, moves the predecessor's lifecycle.status to superseded, and stamps closed_at/closed_by. - Addresses exactly the named claim: on a tuple carrying parallel edges, the siblings are untouched and the subject's properties are carried verbatim. - The predecessor stays resolvable by claim_id afterwards, with its settled state — it is never "gone". - Refused on self-supersession, a missing/non-live/wrong-type successor, a successor that already supersedes another claim, or a predecessor that is not lifecycle-active (or whose review is pending/rejected). A window-expired but active claim IS supersedable.

Common Errors: - Empty or missing --reason. - Permission mode below GRAPH_WRITE. - Successor absent, not live, wrong relationship type, or already recorded as superseding another claim.

cruxible relationship retract

Usage: cruxible relationship retract [OPTIONS] CLAIM_ID

Purpose: Settle a claim as retracted, withdrawn with no successor.

Options And Arguments:

Name	Required	Default	Type	Description
CLAIM_ID	yes	``	argument	Claim ID to retract.
--reason	yes	Sentinel.UNSET	text	Required adjudication reason.
--evidence-ref	no	``	text	Optional evidence reference as a JSON object — a retraction's motivating observation is often a contradiction attestation.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - A settled adjudication at GRAPH_WRITE, recorded in one mutation receipt. - Moves lifecycle.status to retracted and stamps closed_at/closed_by. Properties are carried verbatim: a retraction never rewrites content, and it succeeds even when the type's schema has since grown a required property. - The claim stays resolvable by claim_id afterwards with its settled state. - Refused when the claim is not lifecycle-active, or its review is pending/rejected — resolve the review instead.

Common Errors: - Empty or missing --reason. - Permission mode below GRAPH_WRITE. - The claim is already settled (retracted or superseded).

cruxible relationship get

Usage: cruxible relationship get [OPTIONS]

Purpose: Look up a specific relationship by its endpoints and type.

Options And Arguments:

Name	Required	Default	Type	Description
--from-type	yes	Sentinel.UNSET	text	Source entity type.
--from-id	yes	Sentinel.UNSET	text	Source entity ID.
--relationship	yes	Sentinel.UNSET	text	Relationship type.
--to-type	yes	Sentinel.UNSET	text	Target entity type.
--to-id	yes	Sentinel.UNSET	text	Target entity ID.
--edge-key	no	``	integer	Unstable per-load hint for parallel-edge disambiguation; tuple coordinates remain authoritative.
--ws	no	False	boolean	Also capture this --json read into the agent-local working set (non-authoritative cache; see cruxible ws).
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible relationship lineage

Usage: cruxible relationship lineage [OPTIONS]

Purpose: Inspect a relationship's stored provenance lineage.

Noun-first read of a relationship's lineage.

Options And Arguments:

Name	Required	Default	Type	Description
--from-type	yes	Sentinel.UNSET	text	Source entity type.
--from-id	yes	Sentinel.UNSET	text	Source entity ID.
--relationship	yes	Sentinel.UNSET	text	Relationship type.
--to-type	yes	Sentinel.UNSET	text	Target entity type.
--to-id	yes	Sentinel.UNSET	text	Target entity ID.
--edge-key	no	``	integer	Unstable per-load hint for parallel-edge disambiguation; tuple coordinates remain authoritative.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only. Returns the matching relationship, _provenance, linked proposal group/resolution when provenance points to a group, source workflow receipt ID, source trace IDs, and warnings for missing or non-group provenance.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for read operations. - Ambiguous relationship tuple without --edge-key.

cruxible batch-direct-write

Usage: cruxible batch-direct-write --payload-file PATH [--dry-run] [--json]

Purpose: Validate or apply one structured direct graph write payload containing entities, relationships, and optional payload-local shared evidence.

Options And Arguments:

Name	Required	Default	Type	Description
--payload-file	yes	Sentinel.UNSET	file	JSON or YAML payload containing entities, relationships, and shared_evidence. Use - to read stdin.
--dry-run	no	False	boolean	Validate without mutating graph state.
--json	no	False	boolean	Output as JSON.

Payload Shape:

entities:
  - entity_type: RoadmapItem
    entity_id: ri-example
    properties:
      roadmap_item_id: ri-example
      title: Example roadmap item
relationships:
  - from_type: WorkItem
    from_id: wi-example
    relationship_type: work_item_implements_roadmap_item
    to_type: RoadmapItem
    to_id: ri-example
    shared_evidence_keys: [source_section]
    evidence_rationale: Extracted from the referenced section.
shared_evidence:
  source_section:
    citation_handles:
      - cite1_4f8c3a1d87be76dd3260

Output And Side Effects: - --dry-run validates entity properties, relationship endpoints/properties, evidence locators, duplicate IDs, and missing shared evidence keys without mutating graph state. - Apply mode writes all valid entities and relationships through one mutation receipt and returns a compact summary. Direct writes are live/unreviewed state, not group-reviewed accepted state.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Payload file is not a JSON/YAML object. - Unknown shared evidence key, invalid source-evidence locator, or an unknown, stale, or ambiguous citation handle.

cruxible feedback analyze

Usage: cruxible feedback analyze [OPTIONS]

Purpose: Analyze structured feedback and print remediation suggestions.

Options And Arguments:

Name	Required	Default	Type	Description
--relationship	yes	Sentinel.UNSET	text	Relationship type.
--limit	no	200	integer range	Rows to inspect.
--min-support	no	5	integer range	Minimum support for suggestions.
--decision-surface-type	no	``	choice	Optional decision surface type filter.
--decision-surface-name	no	``	text	Optional decision surface name filter.
--pair	no	Sentinel.UNSET	text	Explicit mismatch pair as FROM_PROP=TO_PROP.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible outcome analyze

Usage: cruxible outcome analyze [OPTIONS]

Purpose: Analyze structured outcomes and print trust/debugging suggestions.

Options And Arguments:

Name	Required	Default	Type	Description
--anchor-type	yes	Sentinel.UNSET	choice	Outcome anchor type to analyze.
--relationship	no	``	text	Relationship type.
--workflow	no	``	text	Workflow name filter.
--query	no	``	text	Query name filter.
--surface-type	no	``	choice	Explicit surface type filter.
--surface-name	no	``	text	Explicit surface name filter.
--limit	no	200	integer range	Rows to inspect.
--min-support	no	5	integer range	Minimum support for suggestions.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible apply

Usage: cruxible apply [OPTIONS]

Purpose: Commit a previously previewed canonical workflow after verifying the preview identity.

Options And Arguments:

Name	Required	Default	Type	Description
--workflow	no	``	text	Workflow name from config.
--input	no	``	text	Inline JSON or YAML workflow input.
--input-file	no	``	path	JSON or YAML file providing workflow input.
--apply-digest	no	``	text	Preview apply digest from workflow run.
--head-snapshot	no	``	text	Expected head snapshot ID from workflow preview.
--preview-file	no	``	file	Read preview state from a file saved by run --save-preview.
--from-last-preview	no	False	boolean	Apply the latest stored preview for the workflow. Mutually exclusive with --preview-file/--apply-digest.
--decision-record	no	``	text	Decision record ID for audit logging.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible clone

Usage: cruxible clone [OPTIONS]

Purpose: Create a new local instance from a chosen snapshot.

Options And Arguments:

Name	Required	Default	Type	Description
--snapshot	yes	Sentinel.UNSET	text	Snapshot ID to clone from.
--root-dir	yes	Sentinel.UNSET	text	Root directory for the new cloned instance.
--activate / --no-activate	no	True	boolean	Make the cloned server instance the active CLI context instance.

Output And Side Effects: - On an auth-enabled daemon the clone is minted its own one-time ADMIN runtime credential (label clone-admin) and the plaintext token is printed exactly once — save it immediately; only its hash is stored and it is never shown again. Auth-disabled daemons mint nothing. - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible config views

Usage: cruxible config views [OPTIONS]

Purpose: Render canonical Mermaid/Markdown views for a Cruxible config.

Options And Arguments:

Name	Required	Default	Type	Description
--config	yes	Sentinel.UNSET	file	Path to config YAML file.
--view	no	all	choice	View to render. 'all' emits the standard config-drafting diagrams.
--bare	no	False	boolean	Emit the raw selected view without Markdown wrapping.
--update-readme	no	Sentinel.UNSET	file	Replace matching CRUXIBLE marker blocks in a README.
--runtime	no	False	boolean	Compose extends overlays as a runtime composed view. This includes inherited ontology/query surfaces but strips upstream build-only workflows.
--composed-ontology	no	False	boolean	With --runtime on an extends config: render the full composed ontology instead of the overlay-scoped view.

Output And Side Effects: - Produces documentation or file output; graph state is not changed.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible context

Usage: cruxible context [OPTIONS]

Purpose: Manage remembered governed server and instance context.

Subcommands:

• cruxible context clear - Clear remembered governed CLI context.
• cruxible context connect - Persist the current governed transport and optional instance.
• cruxible context show - Show the remembered CLI context.
• cruxible context use - Set the active governed instance ID.

Output And Side Effects: - Mutates only the remembered CLI context file, not graph state.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible context clear

Usage: cruxible context clear [OPTIONS]

Purpose: Clear remembered governed CLI context.

Output And Side Effects: - Mutates only the remembered CLI context file, not graph state.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible context connect

Usage: cruxible context connect [OPTIONS]

Purpose: Persist the current governed transport and optional instance.

Options And Arguments:

Name	Required	Default	Type	Description
--server-url	no	``	text	Remote Cruxible server base URL.
--server-socket	no	``	text	Local Cruxible server Unix socket path.
--instance-id	no	``	text	Opaque server-mode instance ID. Defaults to remembered CLI context.

Output And Side Effects: - Mutates only the remembered CLI context file, not graph state.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible context show

Usage: cruxible context show [OPTIONS]

Purpose: Show the remembered CLI context.

Options And Arguments:

Name	Required	Default	Type	Description
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Mutates only the remembered CLI context file, not graph state.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible context use

Usage: cruxible context use [OPTIONS]

Purpose: Set the active governed instance ID.

Options And Arguments:

Name	Required	Default	Type	Description
instance_id	yes	Sentinel.UNSET	text	Positional argument.

Output And Side Effects: - Mutates only the remembered CLI context file, not graph state.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible credential

Usage: cruxible credential [OPTIONS]

Purpose: Manage runtime bearer credentials for a governed server instance.

Subcommands:

• cruxible credential claim-bootstrap - Exchange the one-time bootstrap secret for the first ADMIN runtime token.
• cruxible credential mint - Mint a new runtime bearer credential.
• cruxible credential list - List runtime bearer credentials for the active instance.
• cruxible credential revoke - Revoke a runtime bearer credential.
• cruxible credential rotate - Rotate a runtime bearer credential and print the replacement token once.
• cruxible credential recover-admin - Recover an ADMIN token by local filesystem ownership of server state.

Output And Side Effects: - Server-mode only. Uses the remembered CLI context or --instance-id for the target instance. - Credential creation and rotation print plaintext tokens once. Save them immediately; later list calls show metadata only.

Common Errors: - Missing server transport or missing/stale --instance-id. - Permission mode too low; runtime credential management requires ADMIN. - The bootstrap secret was already claimed or does not match the server secret.

cruxible credential claim-bootstrap

Usage: cruxible credential claim-bootstrap [OPTIONS]

Purpose: Exchange the one-time runtime bootstrap secret for the initial ADMIN runtime token.

Options And Arguments:

Name	Required	Default	Type	Description
--secret-file	no	CRUXIBLE_RUNTIME_BOOTSTRAP_SECRET	file	File containing the runtime bootstrap secret.

Output And Side Effects: - Calls the existing runtime bootstrap claim route for the active instance. - Prints the ADMIN token once with the save hint Save it now, for example: export CRUXIBLE_SERVER_BEARER_TOKEN=<token>.

Common Errors: - Provide --secret-file or set CRUXIBLE_RUNTIME_BOOTSTRAP_SECRET. - The bootstrap secret is invalid or has already been claimed.

cruxible credential mint

Usage: cruxible credential mint [OPTIONS]

Purpose: Mint a new runtime bearer credential for the active server instance.

Options And Arguments:

Name	Required	Default	Type	Description
--label	yes	Sentinel.UNSET	text	Human-readable credential label.
--mode	yes	Sentinel.UNSET	choice	Permission mode: admin, graph_write, governed_write, or read_only.

Output And Side Effects: - Creates an instance-scoped runtime credential and prints its plaintext token once.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low; credential minting requires ADMIN.

cruxible credential list

Usage: cruxible credential list [OPTIONS]

Purpose: List runtime bearer credential metadata for the active server instance.

Output And Side Effects: - Read-only metadata output. Plaintext tokens are never returned by list.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low; credential listing requires ADMIN.

cruxible credential revoke

Usage: cruxible credential revoke [OPTIONS] CREDENTIAL_ID

Purpose: Revoke a runtime bearer credential.

Options And Arguments:

Name	Required	Default	Type	Description
CREDENTIAL_ID	yes	Sentinel.UNSET	argument	Runtime credential ID to revoke.

Output And Side Effects: - Revokes the credential for the active instance and prints updated metadata.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Credential ID not found for the active instance.

cruxible credential rotate

Usage: cruxible credential rotate [OPTIONS] CREDENTIAL_ID

Purpose: Rotate a runtime bearer credential and print the replacement token once.

Options And Arguments:

Name	Required	Default	Type	Description
CREDENTIAL_ID	yes	Sentinel.UNSET	argument	Runtime credential ID to rotate.

Output And Side Effects: - Revokes the old credential, creates a replacement with the same permission mode, and prints the new plaintext token once.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Credential ID not found for the active instance.

cruxible credential recover-admin

Usage: cruxible credential recover-admin [OPTIONS]

Purpose: Recover an ADMIN runtime token by local filesystem ownership of server state. Local-only: refuses to run with any resolved server connection, never contacts a daemon, and treats invoking-uid ownership of --state-dir and its runtime_credentials.db as the recovery authority.

Options And Arguments:

Name	Required	Default	Type	Description
--state-dir	yes	Sentinel.UNSET	path	Server state directory containing runtime_credentials.db. Stop the daemon first; the lock check only refuses a writer caught mid-transaction and does not detect an idle running daemon.
--instance-id	no	None	text	Target instance ID when the credentials DB contains multiple instances.
--label	no	recovered-admin	text	Human-readable label for the recovered ADMIN credential.
--json	no	False	flag	Output as JSON.

Output And Side Effects: - Mints one new ADMIN credential (created_by: local_recovery), records a recovery audit event in the same transaction, and prints the plaintext token once. Existing credentials are not revoked automatically.

Common Errors: - Refused in server mode: unset --server-url/--server-socket (and their environment variables) and run locally. - State dir or credentials DB not owned by the invoking uid. - Credentials DB locked by an active writer, or no ADMIN credential record exists for the target instance.

cruxible decision-record

Usage: cruxible decision-record [OPTIONS]

Purpose: Manage decision records and their logged receipts.

Subcommands:

• cruxible decision-record abandon - Abandon an open decision record.
• cruxible decision-record create - Create an open decision record.
• cruxible decision-record events - List decision-record events.
• cruxible decision-record finalize - Finalize an open decision record.
• cruxible decision-record get - Fetch one decision record.
• cruxible decision-record list - List decision records.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible decision-record abandon

Usage: cruxible decision-record abandon [OPTIONS]

Purpose: Abandon an open decision record.

Options And Arguments:

Name	Required	Default	Type	Description
--id	yes	Sentinel.UNSET	text	Decision record ID.
--reason	no	``	text	Reason for abandoning the record.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible decision-record create

Usage: cruxible decision-record create [OPTIONS]

Purpose: Create an open decision record.

Options And Arguments:

Name	Required	Default	Type	Description
--question	yes	Sentinel.UNSET	text	Question or decision being evaluated.
--subject-type	no	``	text	Optional subject type.
--subject-id	no	``	text	Optional subject identifier.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible decision-record events

Usage: cruxible decision-record events [OPTIONS]

Purpose: List decision-record events.

Options And Arguments:

Name	Required	Default	Type	Description
--id	no	``	text	Decision record ID.
--receipt	no	``	text	Receipt ID.
--trace	no	``	text	Trace ID.
--status	no	``	choice
--limit	no	100	integer range
--offset	no	0	integer range	Rows to skip.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible decision-record finalize

Usage: cruxible decision-record finalize [OPTIONS]

Purpose: Finalize an open decision record.

Options And Arguments:

Name	Required	Default	Type	Description
--id	yes	Sentinel.UNSET	text	Decision record ID.
--final-decision	yes	Sentinel.UNSET	text	Final decision text.
--decision-class	yes	Sentinel.UNSET	choice
--rationale	no	``	text	Decision rationale.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible decision-record get

Usage: cruxible decision-record get [OPTIONS]

Purpose: Fetch one decision record.

Options And Arguments:

Name	Required	Default	Type	Description
--id	yes	Sentinel.UNSET	text	Decision record ID.
--events, --no-events	no	True	boolean
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible decision-record list

Usage: cruxible decision-record list [OPTIONS]

Purpose: List decision records.

Options And Arguments:

Name	Required	Default	Type	Description
--status	no	``	choice
--subject-type	no	``	text
--subject-id	no	``	text
--decision-class	no	``	choice
--limit	no	100	integer range
--offset	no	0	integer range	Rows to skip.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible evaluate

Usage: cruxible evaluate [OPTIONS]

Purpose: Assess graph quality: orphans, gaps, violations, unreviewed co-members.

Options And Arguments:

Name	Required	Default	Type	Description
--limit	no	100	integer	Max findings to show.
--severity	no		choice: error, warning, info	Only return findings at this severity. Repeatable.
--category	no		choice: orphan_entity, coverage_gap, constraint_violation, governed_support_relationship, unreviewed_co_member, quality_check_failed	Only return findings in this category. Repeatable.
--json	no	False	boolean	Output as JSON.

Agent triage example: cruxible evaluate --severity error --limit 1 --json checks whether any error-level finding exists without fetching lower-severity noise. Summaries still reflect the full graph evaluation, not just the filtered findings.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible explain

Usage: cruxible explain [OPTIONS]

Purpose: Explain a query result using its receipt.

Options And Arguments:

Name	Required	Default	Type	Description
--receipt	yes	Sentinel.UNSET	text	Receipt ID to explain.
--format	no	markdown	choice	Output format.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible export

Usage: cruxible export [OPTIONS]

Purpose: Export graph data to files.

Subcommands:

• cruxible export edges - Export all edges to CSV.

Output And Side Effects: - Produces documentation or file output; graph state is not changed.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible export edges

Usage: cruxible export edges [OPTIONS]

Purpose: Export all edges to CSV.

Options And Arguments:

Name	Required	Default	Type	Description
--output, -o	yes	Sentinel.UNSET	file	Output file path.
--relationship	no	``	text	Filter by relationship type.
--exclude-rejected	no	False	boolean	Exclude edges with rejected review_status.

Output And Side Effects: - Produces documentation or file output; graph state is not changed.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible feedback

Usage: cruxible feedback [OPTIONS]

Purpose: Record, batch, analyze, and inspect edge feedback.

Subcommands:

• cruxible feedback record - Submit feedback on a specific edge by explicit relationship coordinates.
• cruxible feedback from-query - Submit edge feedback by selecting relationship evidence from a query receipt.
• cruxible feedback batch - Submit a batch of edge feedback with one top-level receipt.
• cruxible feedback profile - Display the configured feedback profile for one relationship type.
• cruxible feedback analyze - Analyze structured feedback and print remediation suggestions.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible feedback record

Usage: cruxible feedback record [OPTIONS]

Purpose: Submit feedback on a specific edge by explicit relationship coordinates.

Options And Arguments:

Name	Required	Default	Type	Description
--receipt	yes	Sentinel.UNSET	text	Receipt ID.
--action	yes	Sentinel.UNSET	choice	Feedback action: accept, reject, or correct. Deprecated approve delegates to accept; deprecated flag returns its removal refusal.
--from-type	yes	Sentinel.UNSET	text	Source entity type.
--from-id	yes	Sentinel.UNSET	text	Source entity ID.
--relationship	yes	Sentinel.UNSET	text	Relationship type.
--to-type	yes	Sentinel.UNSET	text	Target entity type.
--to-id	yes	Sentinel.UNSET	text	Target entity ID.
--edge-key	no	``	integer	Unstable per-load hint for parallel-edge disambiguation; tuple coordinates remain authoritative.
--reason	no	``	text	Reason for feedback.
--reason-code	no	``	text	Structured feedback reason code.
--scope-hints	no	``	text	JSON object of structured scope hints.
--corrections	no	``	text	JSON object of edge property corrections (for action=correct).
--group-override	no	False	boolean	Mark relationship assertion metadata as a group override (edge must exist).
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible feedback from-query

Usage: cruxible feedback from-query [OPTIONS]

Purpose: Submit edge-level feedback by selecting one relationship row or path segment from a query receipt.

Options And Arguments:

Name	Required	Default	Type	Description
--receipt	yes	Sentinel.UNSET	text	Query receipt ID.
--result-index	yes	Sentinel.UNSET	integer	Zero-based index of the query result row to adjudicate.
--action	yes	Sentinel.UNSET	choice	Feedback action: accept, reject, or correct. Deprecated approve delegates to accept; deprecated flag returns its removal refusal.
--reason	no	``	text	Reason for feedback.
--reason-code	no	``	text	Structured feedback reason code.
--scope-hints	no	``	text	JSON object of structured scope hints.
--corrections	no	``	text	JSON object of edge property corrections (for action=correct).
--group-override	no	False	boolean	Mark selected edge assertion metadata as a group override (edge must exist).
--path-index	no	``	integer	Zero-based path segment index for path query rows.
--path-alias	no	``	text	Traversal alias for the selected path segment.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Creates normal feedback records and feedback receipts through the existing edge-feedback path. - Adjudicates one existing relationship assertion from query evidence. It does not resolve candidate groups. - Use cruxible group get --group <group_id> and cruxible group resolve --group <group_id> --action approve|reject --expected-pending-version <n> when the decision is about a group thesis or member set.

Common Errors: - The receipt is missing, is not a query receipt, or the result index is out of range. - Entity-shaped query rows do not contain relationship evidence. - Multi-hop path rows require exactly one of --path-index or --path-alias. - The selected path alias is missing or duplicated, or the selected edge is no longer in the graph.

cruxible feedback batch

Usage: cruxible feedback batch [OPTIONS]

Purpose: Submit a batch of edge feedback with one top-level receipt.

Options And Arguments:

Name	Required	Default	Type	Description
--items-file	no	``	path	JSON or YAML file with batch feedback items.
--items	no	``	text	Inline JSON array of feedback items.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command. - Batch item actions use accept, reject, or correct; deprecated approve delegates to accept with a warning.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible feedback profile

Usage: cruxible feedback profile [OPTIONS]

Purpose: Display the configured feedback profile for one relationship type.

Options And Arguments:

Name	Required	Default	Type	Description
--relationship	yes	Sentinel.UNSET	text	Relationship type.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible gate

Usage: cruxible gate [OPTIONS]

Purpose: Evaluate declared repo gates against state.

Doctrine: a guard blocks a write INTO state (inbound; the mutation_guards config element); a gate lets the world act only if state agrees (outbound). Gates are outbound exclusively.

Gates are named, kind-based config declarations (the gates: config element). A gate's kind names the source adapter that supplies candidate values: generic accepts caller-supplied values, while git-pre-push derives them from git's pre-push protocol. A candidate is satisfied when at least one entity of the declared type carries it in the declared match property and matches the declared condition. The verb evaluates the declaration; it never hardcodes ontology, and generality comes from source-adapter kinds plus declarative conditions.

Subcommands:

• cruxible gate check - Evaluate a named gate against its kind's candidate values.
• cruxible gate list - Show the active instance's declared gates.

Output And Side Effects: - gate list is read-only. gate check never mutates graph state, but it appends one durable gate-evaluation receipt (including refusals) to the instance audit store.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - No gates: element declared in the active instance config.

cruxible gate check

Usage: cruxible gate check [OPTIONS] NAME

Purpose: Evaluate gate NAME: is every candidate value pinned by satisfying state?

Resolves the named declaration from the active instance config and invokes its declared kind's source adapter for candidate values. The derived values are evaluated server-side as one operation against one state revision (entities of the declared type whose match property equals the candidate AND matching the declared condition), then one composite receipt records the gate, full candidate list, satisfying entity IDs, verdict, instance ID, and observed read revision. Refusals that occur while the daemon is reachable are receipted with verdict=error and a reason. The command prints one verdict line per candidate on stdout (<gate> <value> satisfied|unsatisfied ...); errors go to stderr. The kind determines the supported input: a future source (CI status, webhook) remains a new gate kind against the same evaluation.

The git-pre-push kind reads git's pre-push stdin protocol (lines of <local_ref> <local_sha> <remote_ref> <remote_sha>); run it from the repository root, as git hooks do. Pushed refs are filtered to the adapter config's branch_pattern; every merged-in parent (^2..^N) of each merge commit in the pushed range is a candidate, so an octopus merge passes only when all merged tips are pinned. SHA tokens must be full 40-hex object names (or the all-zeros sentinel); anything else refuses with exit 2. A new remote branch (all-zeros remote SHA) evaluates merges not reachable from any remote-tracking ref; a ref deletion (all-zeros local SHA) is skipped.

The generic kind accepts arbitrary candidate strings from the caller. With no --candidate options it reads one candidate per stdin line, ignores blank lines, and trims surrounding whitespace. Repeatable --candidate VALUE options provide the candidates directly and avoid reading stdin. They are refused for every other kind. Empty or blank-only input fails closed with exit 2.

Options And Arguments:

Name	Required	Default	Type	Description
NAME	yes		argument	Declared gate name (see cruxible gate list).
--candidate	no		text	Candidate value for a generic gate. Repeatable; when present, stdin is not read. Refused for other kinds.
--value	no		text	Hidden diagnostic/test-only override: evaluate these candidate values directly, bypassing the gate's declared source adapter. Repeatable. Not a general primitive — real invocations let the gate's kind derive candidates.

Exit Codes (machine contract):

Code	Meaning
0	every candidate satisfied
1	at least one candidate unsatisfied
2	cannot evaluate (unknown gate, no gates declared, unknown kind, adapter failure, server unreachable, auth failure, malformed input, git failure)

The gate fails closed: every path that cannot produce a verdict exits nonzero with an instructive error on stderr. A gate that silently passes when unconfigured — or whose kind this build cannot evaluate — is forbidden.

Hook one-liner (replaces hand-rolled pre-push scripts):

# .git/hooks/pre-push
exec cruxible gate check merge-review

The git-pre-push kind evaluates merge commits only: squash merges mint new SHAs no review pins, and fast-forward pushes record no merge commit.

Output And Side Effects: - Verdict lines on stdout; errors and notices on stderr. Graph state is read-only; one gate_evaluation receipt is appended to the audit store per invocation.

Common Errors: - Unknown gate name, or no gates: element declared (exit 2). - Gate kind with no source adapter in this build (exit 2). - Daemon unreachable or missing/invalid token in server mode (exit 2). - Empty generic candidates or terminal stdin without --candidate (exit 2). - Empty or malformed pre-push stdin, or failing git commands (exit 2).

cruxible gate list

Usage: cruxible gate list [OPTIONS]

Purpose: Show the active instance's declared gates.

Options And Arguments:

Name	Required	Default	Type	Description
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only output: one line per declared gate (<name> [<kind>]: <EntityType>.<match_property> where <condition> (branch_pattern <pattern>)).

Common Errors: - Missing or stale --instance-id for daemon-backed commands.

cruxible attest

Usage: cruxible attest [OPTIONS] COMMAND [ARGS]...

Purpose: Record and review immutable observations against relationship claims.

Subcommands:

• cruxible attest record - Record one support, contradict, or unsure observation.
• cruxible attest list - List immutable observation history with current tuple markers.
• cruxible attest queue - List live claims with open current-content contradictions.
• cruxible attest resolve - Append a reviewer disposition.

Output And Side Effects:

• Record and resolve require daemon transport so actor attribution and permissions are enforced.
• List and queue are read-only and return standard paged envelopes with --json.
• Attestations and dispositions are append-only; neither mutates the target claim.

cruxible attest record

Usage:

cruxible attest record --relationship REL_TYPE --from-type TYPE --from-id ID --to-type TYPE --to-id ID --stance support|contradict|unsure --observed-at ISO_TIME [--evidence-ref JSON]... [--edge-key INTEGER] [--claim-id CLAIM_ID] [--properties JSON] [--note TEXT] [--idempotency-key KEY] [--json]

Purpose: Record one observation against a tuple-first relationship claim.

Options And Arguments:

Name	Required	Default	Type	Description
--relationship	yes		text	Relationship type of the claim.
--from-type	yes		text	Source endpoint entity type.
--from-id	yes		text	Source endpoint entity ID.
--to-type	yes		text	Target endpoint entity type.
--to-id	yes		text	Target endpoint entity ID.
--stance	yes		choice	support, contradict, or unsure.
--observed-at	yes		text	ISO-8601 time when the world was observed.
--evidence-ref	no		JSON	Evidence pointer; repeatable and required for support or contradict.
--edge-key	no		integer	Disambiguation hint; tuple coordinates remain authoritative.
--claim-id	no		text	Stable claim identity; the preferred disambiguator, taking precedence over --edge-key. Supplying both with disagreeing values is refused.
--properties	no		JSON	Properties used only when absent support creates a pending claim.
--note	no		text	Optional note, encouraged for unsure.
--idempotency-key	no		text	Retry-safe key scoped to actor and claim tuple.
--json	no	False	boolean	Output as JSON.

Output And Side Effects:

• Appends an immutable attestation and receipt.
• If the tuple is absent, support creates a pending claim when both endpoints exist; contradict and unsure refuse.
• If the tuple exists in any state, the observation attaches and any properties payload is ignored with a warning.

cruxible attest list

Usage: cruxible attest list [--claim JSON] [--stance support|contradict|unsure] [--limit N] [--offset N] [--json]

Purpose: List immutable attestation history.

--claim is one JSON object containing exactly relationship_type, from_type, from_id, to_type, and to_id.

Options And Arguments:

Name	Required	Default	Type	Description
--claim	no		JSON	Exact five-coordinate claim tuple.
--stance	no		choice	Optional stance filter.
--limit	no	100	integer	Maximum records.
--offset	no	0	integer	Records to skip.
--json	no	False	boolean	Output as a standard list envelope.

Output And Side Effects: Read-only. Items include latest disposition plus unresolved_target, target_identity_mismatch (with target_identity_mismatch_kind naming which comparison ran: claim_id where both sides carry a minted id, edge_key for legacy records that carry only the per-load key), and stale_content markers.

cruxible attest queue

Usage: cruxible attest queue [--limit N] [--offset N] [--json]

Purpose: List live claims with open current-content contradictions.

Options And Arguments:

Name	Required	Default	Type	Description
--limit	no	100	integer	Maximum per-claim entries.
--offset	no	0	integer	Entries to skip.
--json	no	False	boolean	Output as a standard list envelope.

Output And Side Effects: Read-only. Entries aggregate open contradiction count, distinct contradicting actors, and latest observation time per claim. Unsure and stale-content observations never enter this queue.

cruxible attest resolve

Usage: cruxible attest resolve ATTESTATION_ID --verdict upheld|corrected|invalidated [--note TEXT] [--follow-up-receipt RECEIPT_ID] [--json]

Purpose: Append a reviewer disposition to one immutable attestation.

Options And Arguments:

Name	Required	Default	Type	Description
ATTESTATION_ID	yes		text	Attestation being reviewed.
--verdict	yes		choice	upheld, corrected, or invalidated.
--note	no		text	Optional reviewer explanation.
--follow-up-receipt	no		text	Receipt for a correcting or re-adjudicating action.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: Appends a disposition and receipt. The latest disposition controls derived summary treatment; the claim and original attestation remain unchanged.

cruxible procedure

Usage: cruxible procedure [OPTIONS] COMMAND [ARGS]...

Purpose: Manage governed executable procedures.

Workflows are designed; procedures are learned.

Subcommands:

• cruxible procedure propose - Propose a definition from a JSON or YAML file.
• cruxible procedure list - List definitions, lifecycle state, and run-ledger track records.
• cruxible procedure show - Show one definition, lifecycle record, and run-ledger track record.
• cruxible procedure resolve - Accept or reject a pending definition.
• cruxible procedure withdraw - Retract your own pending proposal.
• cruxible procedure retire - Retire a live definition.
• cruxible procedure run - Execute a live definition.
• cruxible procedure runs - List invocation records.

cruxible procedure propose

Usage: cruxible procedure propose [OPTIONS] DEFINITION_FILE

Purpose: Propose a bounded procedure definition for independent review.

Options And Arguments:

Name	Required	Default	Type	Description
DEFINITION_FILE	yes		file	JSON or YAML procedure definition.
--supersedes	no		text	Procedure ID this immutable replacement supersedes.
--evidence-ref	no		text	JSON evidence-ref object; repeat to attach multiple refs.

Output And Side Effects: - Requires daemon transport and governed_write. - Persists a pending definition and a transition receipt.

cruxible procedure list

Usage: cruxible procedure list [OPTIONS]

Purpose: List governed procedures.

Options And Arguments:

Name	Required	Default	Type	Description
--status	no		choice	Filter by pending, live, rejected, retired, or withdrawn.
--limit	no	100	integer	Maximum definitions to return.
--offset	no	0	integer	Definitions to skip.
--json	no	False	boolean	Emit the standard list envelope.

The JSON result contains items, total, limit, offset, truncated, and read_revision.

Each item carries a track_record block summarizing that procedure's run ledger, so a dead procedure is distinguishable from a healthy one without a second call: runs, the exhaustive verdict buckets succeeded, failed, refused, budget_exceeded, and in_flight (started but not yet finalized), last_succeeded_at, top_refusal_reason, and linked_outcomes (reserved, always null). runs always equals the sum of the five buckets, so a procedure that exhausts its budget on every invocation reads differently from one whose invocations are still running. top_refusal_reason is the most frequently recorded refusal classification and is null when a procedure has never been refused, or when its refusals predate the reason being recorded.

Because these buckets are read state, running a procedure advances read_revision — once when the run starts and once when it is finalized, refusals included — so a truncated procedure page cannot be resumed across an invocation.

cruxible procedure show

Usage: cruxible procedure show [OPTIONS] PROCEDURE_ID

Purpose: Show one procedure definition and lifecycle record.

Options And Arguments:

Name	Required	Default	Type	Description
PROCEDURE_ID	yes		argument	Procedure ID.
--json	no	False	boolean	Emit a procedure object envelope.

The procedure object carries the same track_record block documented under cruxible procedure list.

cruxible procedure resolve

Usage: cruxible procedure resolve [OPTIONS] PROCEDURE_ID

Purpose: Accept or reject one pending procedure.

Options And Arguments:

Name	Required	Default	Type	Description
PROCEDURE_ID	yes		argument	Procedure ID.
--action	yes		choice	accept or reject.
--expected-version	yes		integer	Optimistic lifecycle version.
--reason	no		text	Required by the service when rejecting.

Acceptance requires an independently identified reviewer. This command requires daemon transport and graph_write.

cruxible procedure withdraw

Usage: cruxible procedure withdraw [OPTIONS] PROCEDURE_ID

Purpose: Withdraw your own pending proposal, freeing its name to re-propose.

Options And Arguments:

Name	Required	Default	Type	Description
PROCEDURE_ID	yes		argument	Procedure ID.
--expected-version	yes		integer	Optimistic lifecycle version.
--reason	no		text	Optional note on why it was withdrawn.

The author's counterpart to resolve --action reject: withdrawal is a retraction, not a reviewer verdict, so it needs no reason and lands the definition in withdrawn rather than rejected. The proposing actor may withdraw at their own governed_write tier; withdrawing someone else's pending proposal requires graph_write. A withdrawn definition is not live, so its name is immediately available for a fresh proposal. This command requires daemon transport.

cruxible procedure retire

Usage: cruxible procedure retire [OPTIONS] PROCEDURE_ID

Purpose: Retire one live procedure.

Options And Arguments:

Name	Required	Default	Type	Description
PROCEDURE_ID	yes		argument	Procedure ID.
--expected-version	yes		integer	Optimistic lifecycle version.
--reason	yes		text	Non-empty retirement reason.

This command requires daemon transport and graph_write.

cruxible procedure run

Usage: cruxible procedure run [OPTIONS] PROCEDURE_ID

Purpose: Execute one live procedure through the generic runner.

Options And Arguments:

Name	Required	Default	Type	Description
PROCEDURE_ID	yes		argument	Procedure ID.
--input	yes		text	JSON object validated against contract_in.
--json	no	False	boolean	Emit the execution result as JSON.

This command requires daemon transport. Its permission floor is governed_write; the service also enforces the procedure's effective provider tier.

cruxible procedure runs

Usage: cruxible procedure runs [OPTIONS] PROCEDURE_ID

Purpose: List invocation history for one procedure.

Options And Arguments:

Name	Required	Default	Type	Description
PROCEDURE_ID	yes		argument	Procedure ID.
--limit	no	100	integer	Maximum runs to return.
--offset	no	0	integer	Runs to skip.
--json	no	False	boolean	Emit the standard list envelope.

Text output labels an interrupted record as verdict=null (started/unfinalized tombstone). JSON preserves status: started with verdict: null explicitly.

A run with verdict: refused also carries refusal_reason, the classification counted by the procedure's top_refusal_reason. It is null on every other verdict, and null on refusals recorded before the reason was tracked.

cruxible group

Usage: cruxible group [OPTIONS]

Purpose: Manage candidate groups for batch edge review.

Subcommands:

• cruxible group get - Get details of a candidate group.
• cruxible group list - List candidate groups.
• cruxible group propose - Propose a candidate group of edges for batch review.
• cruxible group resolutions - List group resolutions.
• cruxible group resolve - Resolve a candidate group (approve or reject).
• cruxible group status - Show lifecycle status for a signature bucket.
• cruxible group trust - Update trust status on a resolution.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible group get

Usage: cruxible group get [OPTIONS]

Purpose: Get details of a candidate group.

Options And Arguments:

Name	Required	Default	Type	Description
--group	yes	Sentinel.UNSET	text	Group ID.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible group list

Usage: cruxible group list [OPTIONS]

Purpose: List candidate groups.

Options And Arguments:

Name	Required	Default	Type	Description
--relationship	no	``	text	Filter by relationship type.
--status	no	``	choice	Filter by status.
--limit	no	50	integer	Max groups to show.
--offset	no	0	integer	Rows to skip.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible group propose

Usage: cruxible group propose [OPTIONS]

Purpose: Propose a candidate group of edges for batch review.

Options And Arguments:

Name	Required	Default	Type	Description
--relationship	yes	Sentinel.UNSET	text	Relationship type for the group.
--members-file	no	``	path	JSON file with member list.
--members	no	``	text	Inline JSON array of members.
--thesis	no	``	text	Human-readable thesis text.
--thesis-facts	no	``	text	Optional JSON object used as agent-supplied direct proposal scope.
--analysis-state	no	``	text	JSON object of opaque analysis state.
--signal-source	no	()	text	Deprecated and hidden; signal sources are derived from member signals. Optional, repeatable.
--expected-pending-version	no	``	integer	Optimistic guard: refuse the re-propose if the live pending group is not at this version. Omit for an unconditional refresh.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible group resolutions

Usage: cruxible group resolutions [OPTIONS]

Purpose: List group resolutions.

Options And Arguments:

Name	Required	Default	Type	Description
--relationship	no	``	text	Filter by relationship type.
--action	no	``	choice	Filter by action.
--limit	no	50	integer	Max resolutions to show.
--offset	no	0	integer	Rows to skip.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible group resolve

Usage: cruxible group resolve [OPTIONS]

Purpose: Resolve a candidate group (approve or reject).

Options And Arguments:

Name	Required	Default	Type	Description
--group	yes	Sentinel.UNSET	text	Group ID to resolve.
--action	yes	Sentinel.UNSET	choice	Resolution action.
--rationale	no	``	text	Rationale for this resolution.
--expected-pending-version	yes	Sentinel.UNSET	integer	Pending version the reviewer saw when deciding.
--stamp-existing	no	False	boolean	On approve, bless each surviving pre-existing edge with this group's review status and provenance instead of skipping it.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible group status

Usage: cruxible group status [OPTIONS]

Purpose: Show lifecycle status for a signature bucket.

Options And Arguments:

Name	Required	Default	Type	Description
--group	no	``	text	Concrete group ID.
--signature	no	``	text	Signature bucket ID.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible group trust

Usage: cruxible group trust [OPTIONS]

Purpose: Update trust status on a resolution.

Options And Arguments:

Name	Required	Default	Type	Description
--resolution	yes	Sentinel.UNSET	text	Resolution ID.
--status	yes	Sentinel.UNSET	choice	Trust status to set.
--reason	no	``	text	Reason for trust status change.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible init

Usage: cruxible init [OPTIONS]

Purpose: Initialize a new instance or governed server-backed workspace.

Options And Arguments:

Name	Required	Default	Type	Description
--config	no	``	text	Path to config YAML file.
--kit	no	``	text	Kit alias or ref to materialize; repeatable. Order is composition order: a standalone base kit first, overlay kits after.
--bare	no	False	boolean	Do not compose the configured default base kit during kit init.
--root-dir	no	``	text	Workspace root for config/artifact provenance (defaults to current directory).
--data-dir	no	``	text	Directory for data files.
--bootstrap	no	False	boolean	Use hosted kit init authorized by the runtime bootstrap bearer. Requires --kit.
--activate / --no-activate	no	True	boolean	Make a new server instance the active CLI context instance.

Output And Side Effects: - Normal server init calls the governed instance lifecycle route. With --bootstrap --kit, calls the hosted runtime kit-init route so the one-time bootstrap bearer can create the first auth-enabled instance. - New server instances are remembered in CLI context unless --no-activate is used.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Auth rejecting plain init --kit; run cruxible init --kit <ref> --bootstrap with CRUXIBLE_SERVER_BEARER_TOKEN set to the bootstrap secret, then run cruxible credential claim-bootstrap. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible inspect

Usage: cruxible inspect [OPTIONS]

Purpose: Inspect entities plus canonical read-only system views.

Subcommands:

• cruxible inspect governance - Show the canonical governance view for the current instance.
• cruxible inspect ontology - Show compact topology and authoring contracts for the active ontology.
• cruxible inspect overview - Show the generated config overview built from canonical views.
• cruxible inspect queries - Show the canonical query view for the current instance config.
• cruxible inspect trace - Inspect a provider execution trace by ID.
• cruxible inspect workflows - Show the canonical workflow view for the current instance config.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible inspect governance

Usage: cruxible inspect governance [OPTIONS]

Purpose: Show the canonical governance view for the current instance.

Options And Arguments:

Name	Required	Default	Type	Description
--format	no	markdown	choice	Output format.
--limit	no	200	integer range	Max pending groups and resolutions to inspect.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible inspect trace

Usage: cruxible inspect trace [OPTIONS] TRACE_ID

Purpose: Inspect a provider execution trace by ID.

Options And Arguments:

Name	Required	Default	Type	Description
trace_id	yes	Sentinel.UNSET	text	Positional argument.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only. Returns the persisted provider execution trace, including provider metadata, retained input/output payload fields, payload digest/size metadata, status, timings, and error details when present. Payload fields follow the instance config's runtime.trace_payloads retention policy.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Trace ID not found. - Permission mode too low for read operations.

cruxible inspect ontology

Usage: cruxible inspect ontology [OPTIONS]

Purpose: Show compact topology and authoring contracts for the active ontology.

Options And Arguments:

Name	Required	Default	Type	Description
--format	no	markdown	choice	Output format.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible inspect overview

Usage: cruxible inspect overview [OPTIONS]

Purpose: Show the generated config overview built from canonical views.

Options And Arguments:

Name	Required	Default	Type	Description
--format	no	markdown	choice	Output format.
--limit	no	200	integer range	Max pending groups and resolutions to inspect.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible inspect queries

Usage: cruxible inspect queries [OPTIONS]

Purpose: Show the canonical query view for the current instance config.

Options And Arguments:

Name	Required	Default	Type	Description
--format	no	markdown	choice	Output format.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible inspect workflows

Usage: cruxible inspect workflows [OPTIONS]

Purpose: Show the canonical workflow view for the current instance config.

Options And Arguments:

Name	Required	Default	Type	Description
--format	no	markdown	choice	Output format: json, markdown, mermaid, mermaid-dependencies, or mermaid-steps.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible lint

Usage: cruxible lint [OPTIONS]

Purpose: Run the aggregate read-only corpus lint pass.

Options And Arguments:

Name	Required	Default	Type	Description
--max-findings	no	100	integer	Max graph findings to include.
--analysis-limit	no	200	integer	Rows to inspect for feedback and outcome analysis.
--min-support	no	5	integer	Minimum support for lint suggestions.
--exclude-orphan-type	no	Sentinel.UNSET	text	Entity type to exclude from orphan checks.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible list

Usage: cruxible list [OPTIONS]

Purpose: List entities, receipts, or feedback.

Subcommands:

• cruxible list edges - List edges in the graph.
• cruxible list entities - List entities of a given type.
• cruxible list feedback - List feedback records.
• cruxible list outcomes - List outcome records.
• cruxible list receipts - List receipt summaries.
• cruxible list traces - List provider execution trace summaries.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible list edges

Usage: cruxible list edges [OPTIONS]

Purpose: List edges in the graph.

Options And Arguments:

Name	Required	Default	Type	Description
--relationship	no	``	text	Filter by relationship type.
--where	no	``	text	Property predicate. Repeatable. Use field=value, field~value, or field:in=a,b.
--limit	no	50	integer	Max edges to show.
--offset	no	0	integer	Rows to skip.
--state	no	``	choice	Read-visibility state: live, accepted, all, not-live, pending, or reviewable. Omit to return every stored edge (the inspection default); not-live surfaces rejected/closed edges, live hides them.
--lifecycle-status	no	``	choice	Exact kind-correct lifecycle status to read: relationships take active/inactive/superseded/retracted, entities take live/retired/superseded. Orthogonal to --state: --state is the coarse visibility selector, this is an exact-match filter on the lifecycle axis. Vocabulary from the wrong kind is refused.
--profile	no	standard	choice	JSON output profile: compact (bounded identity cards with governance markers), standard (full shape), or full (reserved superset of standard).
--continue	no	``	text	Continuation token from a previous truncated page; repeat the same filters. Bound to the instance, config, and read_revision — stale after any state mutation (restart the read); malformed tokens are rejected.
--ws	no	False	boolean	Also capture this --json read into the agent-local working set (non-authoritative cache; see cruxible ws).
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event. - list edges is a stored-relationship inspection surface. With no --state it returns every stored edge, including pending, rejected, or otherwise non-live ones. Pass --state live (or use named queries, which are logical reads) when you need live/reviewable truth rather than store inspection; --state not-live surfaces exactly the rejected/closed edges for recovery. - Example: cruxible list edges --relationship work_item_depends_on_work_item --where dependency_basis~schema --json

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible list entities

Usage: cruxible list entities [OPTIONS]

Purpose: List entities of a given type.

Options And Arguments:

Name	Required	Default	Type	Description
--type	yes	Sentinel.UNSET	text	Entity type to list.
--field	no	``	text	Property field to include. Repeat to project compact entity payloads.
--where	no	``	text	Property predicate. Repeatable. Use field=value, field~value, or field:in=a,b.
--limit	no	50	integer	Max entities to show.
--offset	no	0	integer	Rows to skip.
--state	no	``	choice	Read-visibility state by entity lifecycle: live (default — hides retired/superseded entities), all, or not-live (only the gated-out set). Review-only values resolve to live (entities have no review axis).
--lifecycle-status	no	``	choice	Exact kind-correct lifecycle status to read: relationships take active/inactive/superseded/retracted, entities take live/retired/superseded. Orthogonal to --state: --state is the coarse visibility selector, this is an exact-match filter on the lifecycle axis. Vocabulary from the wrong kind is refused.
--profile	no	standard	choice	JSON output profile: compact (bounded identity cards with governance markers), standard (full shape), or full (reserved superset of standard).
--continue	no	``	text	Continuation token from a previous truncated page; repeat the same filters. Bound to the instance, config, and read_revision — stale after any state mutation (restart the read); malformed tokens are rejected.
--ws	no	False	boolean	Also capture this --json read into the agent-local working set (non-authoritative cache; see cruxible ws).
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only. Defaults to --state live: retired/superseded entities (entity lifecycle.status != live) are hidden. Use --state not-live to find the gated-out set (recovery), or --state all for everything. Without --field, returns full entity records. With --field, returns the same list envelope but trims each entity's properties to the requested fields while always keeping entity_type and entity_id. - --where filters configured entity properties after the caller has selected an entity type. It is bounded predicate filtering, not topic or semantic search. Examples: cruxible list entities --type WorkItem --where status=active --field title --json and cruxible list entities --type WorkItem --where title~query --field status --json. - Field projection reduces payload size after the caller has already selected an entity type; it is not topic search. - The --json envelope carries read_revision (state freshness marker; receipts prove computation, never freshness) and continuation_token (present iff truncated and resumable). Truncated table output prints the resume hint; continue with --continue TOKEN and the same filters.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible list feedback

Usage: cruxible list feedback [OPTIONS]

Purpose: List feedback records.

Options And Arguments:

Name	Required	Default	Type	Description
--receipt	no	``	text	Filter by receipt ID.
--limit	no	50	integer	Max records to show.
--offset	no	0	integer	Rows to skip.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible list outcomes

Usage: cruxible list outcomes [OPTIONS]

Purpose: List outcome records.

Options And Arguments:

Name	Required	Default	Type	Description
--receipt	no	``	text	Filter by receipt ID.
--limit	no	50	integer	Max records to show.
--offset	no	0	integer	Rows to skip.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible list receipts

Usage: cruxible list receipts [OPTIONS]

Purpose: List receipt summaries.

Options And Arguments:

Name	Required	Default	Type	Description
--query-name	no	``	text	Filter by query name.
--operation-type	no	``	text	Filter by operation type.
--limit	no	50	integer	Max receipts to show.
--offset	no	0	integer	Rows to skip.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible list traces

Usage: cruxible list traces [OPTIONS]

Purpose: List provider execution trace summaries.

Options And Arguments:

Name	Required	Default	Type	Description
--workflow	no	``	text	Filter by workflow name.
--provider	no	``	text	Filter by provider name.
--limit	no	100	integer range	Max traces to show.
--offset	no	0	integer range	Rows to skip.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only. Returns trace summary rows with trace ID, workflow, step, provider, runtime, and creation time.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for read operations. - Invalid limit or offset.

cruxible lock

Usage: cruxible lock [OPTIONS]

Purpose: Generate a workflow lock file for the current instance config, or for a bare kit directory with --kit-dir.

Options And Arguments:

Name	Required	Default	Type	Description
--force	no	False	boolean	Accept live canonical artifact hashes when regenerating the lock.
--kit-dir	no	``	directory	Build <kit-dir>/cruxible.lock.yaml from <kit-dir>/config.yaml without loading an instance or contacting a daemon.

Output And Side Effects: - Without --kit-dir, updates the active instance workflow lock through the local service layer or configured daemon. - With --kit-dir, performs a pure local kit lock refresh: reads the kit's own config layer (no target_state composition — base-layer content is pinned by the base kit's own lock), writes <kit-dir>/cruxible.lock.yaml with artifact URIs preserved as written, and prints the lock digest. This is the canonical generation path for a committed kit lock; CI asserts regen-is-noop for every bundled kit.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - --kit-dir cannot be combined with explicit server transport flags or --instance-id, and the kit directory must contain config.yaml. - Canonical artifact digest mismatches fail unless --force is used to accept the on-disk hash. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible kit

Usage: cruxible kit [OPTIONS]

Purpose: Manage local materialized kits.

Subcommands:

• cruxible kit repin - Accept intentional runtime-file edits in a materialized kit.

Output And Side Effects: - Writes only explicitly requested local materialized-kit metadata.

Common Errors: - The selected directory is not a materialized kit.

cruxible kit repin

Usage: cruxible kit repin [OPTIONS]

Purpose: Recompute a materialized kit's runtime digest after intentional local edits and re-record it in .cruxible/kit.json.

Options And Arguments:

Name	Required	Default	Type	Description
--kit-dir	no	.	directory	Materialized kit root. Defaults to the current directory.

Output And Side Effects: - Preserves the materialization metadata and replaces only its runtime_digest, printing the old and new digests. - Does not materialize a kit. An existing .cruxible/kit.json is required. - CRUXIBLE_KIT_DEV_RESOLVE=1 remains available for CI development checks, but intentional local edits should use this command.

Common Errors: - .cruxible/kit.json is missing or invalid. - Materialized metadata does not match cruxible-kit.yaml. - A declared runtime path is invalid or contains a symlink.

cruxible outcome

Usage: cruxible outcome [OPTIONS]

Purpose: Record, analyze, and inspect decision outcomes.

Subcommands:

• cruxible outcome open - Open a resolution contract on a subject before it is accepted.
• cruxible outcome resolve - Record what reality said about one activated resolution contract.
• cruxible outcome dispose - Uphold or overturn a recorded outcome.
• cruxible outcome list - List resolution contracts with status, activation, and standing answer.
• cruxible outcome due - List outcomes due for checking, overdue, or contradicted and undisposed.
• cruxible outcome record - Record the outcome of a decision.
• cruxible outcome profile - Display the configured outcome profile for one anchor context.
• cruxible outcome analyze - Analyze structured outcomes and print trust/debugging suggestions.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible outcome record

Usage: cruxible outcome record [OPTIONS]

Purpose: Record the outcome of a decision.

Options And Arguments:

Name	Required	Default	Type	Description
--receipt	yes	Sentinel.UNSET	text	Receipt ID.
--outcome	yes	Sentinel.UNSET	choice	Outcome of the decision.
--detail	no	``	text	JSON string with outcome details.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible outcome profile

Usage: cruxible outcome profile [OPTIONS]

Purpose: Display the configured outcome profile for one anchor context.

Options And Arguments:

Name	Required	Default	Type	Description
--anchor-type	yes	Sentinel.UNSET	choice	Anchor type to resolve.
--relationship	no	``	text	Relationship type.
--workflow	no	``	text	Workflow name.
--surface-type	no	``	choice	Receipt surface type.
--surface-name	no	``	text	Receipt surface name.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible outcome open

Usage:

cruxible outcome open --entity-type TYPE --entity-id ID --description TEXT --check-at ISO_TIME --expires-at ISO_TIME --measurement JSON [--idempotency-key KEY] [--json]

Purpose: Open a resolution contract on a subject before it is accepted.

Options And Arguments:

Name	Required	Default	Type	Description
--entity-type	yes		text	Subject entity type; the subject must already exist.
--entity-id	yes		text	Subject entity ID.
--description	yes		text	Free-text success criterion that survives mechanical rot.
--check-at	yes		text	ISO-8601 time when the outcome is first checked; must precede --expires-at.
--expires-at	yes		text	ISO-8601 time when an unresolved contract ages into overdue.
--measurement	yes		JSON	Measurement declaration: {kind: query, ...} or {kind: attestation, ...}.
--idempotency-key	no		text	Retry-safe key scoped to the subject and resolved actor.
--json	no	False	boolean	Output as JSON.

Output And Side Effects:

• Appends an immutable contract and receipt; the subject is never mutated.
• Pins the measurement query's definition digest AND its effective execution options (relationship_state, result_shape, dedupe), so a later receipt run under other options cannot resolve the contract.
• Requires daemon transport so actor attribution and permissions are enforced.
• Multiple open contracts on one subject are legal; each is answered separately.

Common Errors: - The subject does not exist yet — propose the record first, then open the contract. - No requires_resolution_contract mutation guard covers the subject's entity type. Declare the guard on the accepting transition before opening; see the outcome_tracking adoption convention. - --check-at at or after --expires-at, or a measurement query that is not defined in named_queries. - A measurement param key the query cannot read (typos are refused, not ignored). - A condition-only expectation with condition_scope: all and no min_count — an ALL condition over zero rows is vacuously satisfied. - Reusing an idempotency key with a different declaration.

cruxible outcome resolve

Usage:

cruxible outcome resolve CONTRACT_ID --verdict satisfied|contradicted|indeterminate --observed-at ISO_TIME [--evidence-ref JSON]... [--note TEXT] [--query-receipt RECEIPT_ID] [--attestation ATTESTATION_ID]... [--json]

Purpose: Record what reality said about one activated resolution contract.

Options And Arguments:

Name	Required	Default	Type	Description
CONTRACT_ID	yes		text	Activated contract being answered.
--verdict	yes		choice	satisfied, contradicted, or indeterminate.
--observed-at	yes		text	ISO-8601 observation time; satisfied requires it at or after check_at.
--evidence-ref	no		JSON	Evidence pointer; repeatable and required for satisfied or contradicted.
--note	no		text	Observation note; required for contradicted.
--query-receipt	no		text	Receipt of the query run that observed a query-measured outcome.
--attestation	no		text	Attestation id backing an attestation-measured outcome; repeatable.
--json	no	False	boolean	Output as JSON.

Output And Side Effects:

• Appends one immutable resolution and receipt; the subject is never mutated.
• A contract accepts exactly one standing resolution; a second attempt refuses until a reviewer overturns the first.
• Requires daemon transport so actor attribution and permissions are enforced.

Common Errors: - The contract was never activated by a successful requires_resolution_contract-guarded acceptance, or already carries a standing resolution. A prepared contract has nothing to resolve and expires without activation. - The resolving receipt ran a different query, different params, different execution options (e.g. a relationship_state override), was truncated, or contradicts the verdict. - The resolving receipt was created before the contract was opened, carries no read_revision stamp, or — for satisfied — was created before the declared check time. The evidence's own clock is what settles the timing, not the caller's --observed-at. - A cited attestation predates the contract's opening, was invalidated by a reviewer disposition, or — for satisfied — is older than the declared check time. - The measurement query changed since the contract was opened — only indeterminate remains available.

cruxible outcome dispose

Usage:

cruxible outcome dispose RESOLUTION_ID --verdict upheld|overturned [--note TEXT] [--json]

Purpose: Uphold or overturn a recorded outcome.

Options And Arguments:

Name	Required	Default	Type	Description
RESOLUTION_ID	yes		text	Immutable resolution being reviewed.
--verdict	yes		choice	upheld or overturned.
--note	no		text	Reviewer note.
--json	no	False	boolean	Output as JSON.

Output And Side Effects:

• Appends a disposition and receipt; an overturned verdict re-opens the contract for exactly one further resolution.
• Dispositions are latest-wins: recording another one on the same resolution supersedes the previous answer (a mistaken upheld is corrected this way), and every read reports the newest.
• Requires daemon transport and a reviewer-tier credential.

Common Errors: - The resolution does not exist. - The disposition being revised was an overturned that a later resolution already answered — dispose that resolution instead. - Permission mode below GRAPH_WRITE.

cruxible outcome list

Usage:

cruxible outcome list [--entity-type TYPE] [--entity-id ID] [--status prepared|open|resolved] [--limit N] [--offset N] [--json]

Purpose: List resolution contracts with status, activation, and standing answer.

Options And Arguments:

Name	Required	Default	Type	Description
--entity-type	no		text	Filter to one subject entity type.
--entity-id	no		text	Filter to one subject entity ID.
--status	no		choice	Filter the returned page by derived status.
--limit	no	100	integer range	Contracts per page.
--offset	no	0	integer range	Contracts to skip.
--json	no	False	boolean	Output as JSON.

Output And Side Effects:

• Read-only; returns the standard paged envelope with --json.
• Marks expiry, subject presence, and subject-content drift per contract.
• --status filters the returned page only; total stays the unfiltered store count.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - --limit below 1 or --offset below 0.

cruxible outcome due

Usage:

cruxible outcome due [--queue due|overdue|contradicted] [--limit N] [--offset N] [--json]

Purpose: List outcomes due for checking, overdue, or contradicted and undisposed.

Options And Arguments:

Name	Required	Default	Type	Description
--queue	no	due	choice	due (past check time), overdue (past expiry), or contradicted (undisposed).
--limit	no	100	integer range	Entries per page.
--offset	no	0	integer range	Entries to skip.
--json	no	False	boolean	Output as JSON.

Output And Side Effects:

• Read-only; returns the standard paged envelope with --json.
• Lists only activated contracts on live subjects; prepared contracts expire without ever demanding attention.
• due includes past-expiry contracts (the check is still owed) and marks them overdue.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - --limit below 1 or --offset below 0.

cruxible plan

Usage: cruxible plan [OPTIONS]

Purpose: Compile a workflow plan for the current instance.

Options And Arguments:

Name	Required	Default	Type	Description
--workflow	yes	Sentinel.UNSET	text	Workflow name from config.
--input	no	``	text	Inline JSON or YAML workflow input.
--input-file	no	``	path	JSON or YAML file providing workflow input.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible propose

Usage: cruxible propose [OPTIONS]

Purpose: Execute a type: proposal workflow and bridge its output into a candidate group.

Options And Arguments:

Name	Required	Default	Type	Description
--workflow	yes	Sentinel.UNSET	text	Workflow name from config.
--input	no	``	text	Inline JSON or YAML workflow input.
--input-file	no	``	path	JSON or YAML file providing workflow input.
--decision-record	no	``	text	Decision record ID for audit logging.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible query

Usage: cruxible query [OPTIONS]

Purpose: Run, inspect, and discover named queries on this instance.

Subcommands:

• cruxible query describe - Describe one named query with required params and example IDs.
• cruxible query inline - Execute a bounded inline query definition for exploration.
• cruxible query list - List named queries as bounded summaries.
• cruxible query run - Execute a named query and display results plus the receipt.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible query run

Usage: cruxible query run [OPTIONS] QUERY_NAME

Purpose: Execute a named query and display results plus the receipt.

Options And Arguments:

Name	Required	Default	Type	Description
query_name	yes	Sentinel.UNSET	text	Positional argument.
--param	no	Sentinel.UNSET	text	Query parameter as KEY=VALUE.
--limit	no	``	integer range	Max results to display.
--state	no	``	choice	Read-visibility state: live (default), accepted, all, not-live, pending, or reviewable. Gates entities by lifecycle and edges by review+lifecycle. Overriding a named query's configured state requires allow_relationship_state_override: true.
--lifecycle-status	no	``	choice	Exact kind-correct lifecycle status to read: relationships take active/inactive/superseded/retracted, entities take live/retired/superseded. Orthogonal to --state: --state is the coarse visibility selector, this is an exact-match filter on the lifecycle axis. Vocabulary from the wrong kind is refused.
--count	no	False	boolean	Show only summary metadata.
--decision-record	no	``	text	Decision record ID for audit logging.
--profile	no	standard	choice	JSON output profile: compact (bounded identity cards with governance markers), standard (full shape), or full (reserved superset of standard).
--layout	no	rows	choice	Query output layout: rows (per-row items) or graph (normalized nodes/edges with results as ordered references; compact graph interns repeated non-empty include maps in include_sets).
--ws	no	False	boolean	Also capture this --json read into the agent-local working set (non-authoritative cache; see cruxible ws).
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible query inline

Usage: cruxible query inline [OPTIONS]

Purpose: Execute a bounded inline query definition without persisting it to config.

Options And Arguments:

Name	Required	Default	Type	Description
--definition-json	no	``	text	Inline query definition as a JSON object.
--definition-file	no	``	path	Path to a JSON or YAML inline query definition.
--param	no	Sentinel.UNSET	text	Query parameter as KEY=VALUE.
--limit	no	``	integer range	Max results to display.
--state	no	``	choice	Read-visibility state: live (default), accepted, all, not-live, pending, or reviewable. Gates entities by lifecycle and edges by review+lifecycle. Overriding the inline definition's configured state requires allow_relationship_state_override: true.
--lifecycle-status	no	``	choice	Exact kind-correct lifecycle status to read: relationships take active/inactive/superseded/retracted, entities take live/retired/superseded. Orthogonal to --state: --state is the coarse visibility selector, this is an exact-match filter on the lifecycle axis. Vocabulary from the wrong kind is refused.
--layout	no	rows	choice	Query output layout: rows (per-row items) or graph (normalized nodes/edges with results as ordered references; compact graph interns repeated non-empty include maps in include_sets).
--count	no	False	boolean	Show only summary metadata.
--decision-record	no	``	text	Decision record ID for audit logging.
--json	no	False	boolean	Output as JSON.

Example:

cruxible query inline \
  --definition-json '{"name":"brake_parts","mode":"collection","returns":"Part","result_shape":"entity","where":{"result.properties.category":{"eq":"brakes"}}}' \
  --json

Output And Side Effects: - Read-only graph access. Inline queries persist query receipts and optional decision events, but they do not modify or persist config.

Common Errors: - Provide exactly one of --definition-json or --definition-file. - Inline query definitions use the same shape as configured named queries plus required name; repeated or workflow-critical inline queries should be accepted into config as named queries.

cruxible query describe

Usage: cruxible query describe [OPTIONS]

Purpose: Describe one named query with required params and example IDs.

Options And Arguments:

Name	Required	Default	Type	Description
--query	yes	Sentinel.UNSET	text	Named query from config.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible query list

Usage: cruxible query list [OPTIONS]

Purpose: List named queries as bounded summaries (name, mode, entry point, returns, required params). Use cruxible query describe --query NAME for one query's full definition.

Options And Arguments:

Name	Required	Default	Type	Description
--detail	no	summary	choice	summary (default) is a bounded discovery card; full adds state/dedupe/example columns to the table and emits complete definitions with --json.
--continue	no	``	text	Continuation token from a previous truncated page (same --detail). Stale after any state mutation — restart the read.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible config reload

Usage: cruxible config reload [OPTIONS]

Purpose: Validate the active config or repoint the instance to a new config file.

Options And Arguments:

Name	Required	Default	Type	Description
--config	no	``	text	Optional new config path.
--allow-orphans	no	False	flag	Allow stored graph types absent from the incoming config.

Output And Side Effects: - Refuses the reload (before any file or pointer changes) if the incoming config no longer declares entity or relationship types present in the stored graph; the error lists each stranded type with its stored count. --allow-orphans proceeds anyway and the output carries the stranding report. - Successful reloads print the type delta (entity/relationship types added and removed) so a reload is never a silent schema change. A reload whose current config is unreadable still works as the repair path; the delta is reported as unknown via a warning. - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible config status

Usage: cruxible config status [--config PATH] [--json]

Purpose: Distinguish authored-source drift from out-of-band edits to the active materialized config.

Options And Arguments:

Name	Required	Default	Type	Description
--config	no	``	text	Authored root config to compare with the active materialization.
--json	no	False	boolean	Output as JSON.

Pass the same authored root used for reload:

cruxible config status --config path/to/composed-config.yaml

The command reports one of five states: in_sync, source_changed, materialized_modified, source_unchecked, or untracked. Source or active drift exits nonzero so the command can be used by hooks and CI. Omitting --config verifies the active bytes only.

cruxible run

Usage: cruxible run [OPTIONS]

Purpose: Execute a workflow for the current instance. Canonical workflows run as previews and return an apply_digest plus head_snapshot_id; use cruxible apply to commit them. For type: proposal workflows, use cruxible propose instead.

Options And Arguments:

Name	Required	Default	Type	Description
--workflow	yes	Sentinel.UNSET	text	Workflow name from config.
--input	no	``	text	Inline JSON or YAML workflow input.
--input-file	no	``	path	JSON or YAML file providing workflow input.
--save-preview	no	``	file	Save preview state to a JSON file for use with apply --preview-file.
--decision-record	no	``	text	Decision record ID for audit logging.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible sample

Usage: cruxible sample [OPTIONS]

Purpose: Show a sample of entities of a given type.

Options And Arguments:

Name	Required	Default	Type	Description
--type	yes	Sentinel.UNSET	text	Entity type to sample.
--field	no	``	text	Property field to include. Repeat to project compact entity payloads.
--limit	no	5	integer	Number of entities to show.
--ws	no	False	boolean	Also capture this --json read into the agent-local working set (non-authoritative cache; see cruxible ws).
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only. Without --field, returns full sampled entity records. With --field, trims each entity's properties to the requested fields while always keeping entity_type and entity_id. - The --json envelope reports the TRUE stored total for the type and sets truncated whenever the sample did not cover it — a sample is an explicit, never a silent, truncation. read_revision marks state freshness.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible schema

Usage: cruxible schema [OPTIONS]

Purpose: Display the config schema for this instance.

Options And Arguments:

Name	Required	Default	Type	Description
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible server

Usage: cruxible server [OPTIONS]

Purpose: Launch and inspect the Cruxible daemon.

Subcommands:

• cruxible server start - Launch the Cruxible daemon in the foreground (the only daemon launch path).
• cruxible server status - Report a running daemon's version, state dir, transport, and instances.
• cruxible server info - Show live daemon metadata such as auth mode and state dir.
• cruxible server restart - Re-exec the live daemon in place, preserving its port, state dir, and env.

Client Vs Launch: - start LAUNCHES the daemon; it takes no --server-url and becomes the long-running daemon process. - status, info, and restart are CLIENT RPCs against an already-running daemon: they need a transport (--server-url / --server-socket or the matching env vars) and fail with a clear message when no daemon is reachable.

Output And Side Effects: - Command-specific output only.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible server start

Usage: cruxible server start [OPTIONS]

Purpose: Launch the Cruxible daemon in the foreground.

Options And Arguments:

Name	Required	Default	Type	Description
--host	no	CRUXIBLE_HOST or 127.0.0.1	text	Bind host. Ignored when --socket is set.
--port	no	CRUXIBLE_PORT or 8100	integer	Bind port. Ignored when --socket is set.
--state-dir	no	CRUXIBLE_SERVER_STATE_DIR or ~/.cruxible/server	text	Server-owned state directory.
--socket	no	CRUXIBLE_SERVER_SOCKET	text	Listen on this Unix socket path instead of host/port.
--capability-ceiling	no	CRUXIBLE_MODE or admin	choice	Immutable daemon capability ceiling. Bearer credentials cannot exceed it.
--bootstrap-secret-file	no	``	file	Write an auto-generated runtime bootstrap secret to this file with mode 0600.

Output And Side Effects: - This process becomes the long-running daemon (it is not a client of an existing one, so it takes no --server-url). Flags override the matching environment variables (CRUXIBLE_HOST, CRUXIBLE_PORT, CRUXIBLE_SERVER_STATE_DIR, CRUXIBLE_SERVER_SOCKET); unset flags fall back to the env value or the built-in default. Use a durable --state-dir; Cruxible warns at startup when the state path resolves under a volatile temp location. Stop with Ctrl-C. cruxible server start --help prints help and exits without serving. - When CRUXIBLE_SERVER_AUTH=true and no CRUXIBLE_RUNTIME_BOOTSTRAP_SECRET is set, generates a one-time bootstrap secret. Without --bootstrap-secret-file, prints it once with hosted-init and claim hints. With --bootstrap-secret-file, writes it to that path as 0600 and prints only the path plus hosted-init and claim hints.

Common Errors: - Binding a non-loopback host without CRUXIBLE_SERVER_AUTH=true is refused. - A state dir that previously required auth is refused unless auth is re-enabled. - The daemon ships in the default install (pip install cruxible); no extra is required.

cruxible server status

Usage: cruxible server status [OPTIONS]

Purpose: Report a running daemon's version, state dir, transport, and instances.

Options And Arguments:

Name	Required	Default	Type	Description
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - A CLIENT command: queries an already-running daemon over the configured transport (--server-url / --server-socket or the matching env vars) and prints whether it is reachable, plus its version, state directory, configured transport, instance count, and auth status. With --json, returns the same fields plus transport.

Common Errors: - No transport configured, or the daemon is down: fails with a clear message (no hang) pointing at cruxible server start / --server-url. - Permission mode too low to read cross-tenant daemon metadata.

cruxible server info

Usage: cruxible server info [OPTIONS]

Purpose: Show live daemon metadata such as auth mode and state dir.

Options And Arguments:

Name	Required	Default	Type	Description
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Prints daemon version, server requirement, auth enabled/required status, state directory, and instance count. With --json, returns the same fields.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible server restart

Usage: cruxible server restart [OPTIONS]

Purpose: Re-exec the live daemon in place, preserving its port, state dir, and env.

Options And Arguments:

Name	Required	Default	Type	Description
--json	no	False	boolean	Output as JSON.
--no-wait	no	False	boolean	Return immediately after scheduling the restart, without confirming the daemon is back.
--timeout	no	30.0	float	Seconds to wait for the restarted daemon to answer again.

Output And Side Effects: - Replaces the daemon's own process image (os.execv), preserving port, state directory, and environment, so it picks up code changes without losing its transport or instances. By default waits for the new image to answer and prints the confirmed version; --no-wait skips the wait. Requires ADMIN.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible snapshot

Usage: cruxible snapshot [OPTIONS]

Purpose: Manage immutable state snapshots.

Subcommands:

• cruxible snapshot create - Create an immutable full snapshot for the current instance.
• cruxible snapshot list - List snapshots for the current instance.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible snapshot create

Usage: cruxible snapshot create [OPTIONS]

Purpose: Create an immutable full snapshot for the current instance.

Options And Arguments:

Name	Required	Default	Type	Description
--label	no	``	text	Optional human label for the snapshot.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible snapshot list

Usage: cruxible snapshot list [OPTIONS]

Purpose: List snapshots for the current instance.

Options And Arguments:

Name	Required	Default	Type	Description
--limit	no	``	integer	Max snapshots to show.
--offset	no	0	integer	Rows to skip.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible source

Usage: cruxible source [OPTIONS] COMMAND [ARGS]...

Purpose: Register local source documents and dereference source-backed evidence locators.

Subcommands:

• cruxible source list - List registered source artifact summaries.
• cruxible source get - Read one registered source artifact's metadata and chunk map.
• cruxible source register - Parse and register a local Markdown source artifact.
• cruxible source dereference - Resolve a registered source-evidence locator back to source text.

Output And Side Effects: - source list, source get, and source dereference are read-only. - source register writes a source artifact manifest, parsed chunk metadata, and optional archived source bytes into the current instance.

Common Errors: - Missing local instance or stale daemon --instance-id. - Permission mode too low for governed write/read operations. - Unsupported source kind, missing local source path, incomplete locator, or drifted source content hash.

cruxible source list

Usage: cruxible source list [OPTIONS]

Purpose: List registered source artifact summaries for the current instance.

Options And Arguments:

Name	Required	Default	Type	Description
--limit	no	50	integer	Max artifacts to show.
--offset	no	0	integer	Rows to skip.
--json	no	False	boolean	Output the full list contract payload as JSON.

Output And Side Effects: - Read-only. Human output renders a table with artifact id, current revision handle, kind, label, retention, chunk count, and registration timestamp, followed by total and truncated pagination status. - With --json, emits the full SourceArtifactListResult contract payload.

Common Errors: - Missing local instance or stale daemon --instance-id. - Permission mode too low for source artifact reads. - Invalid negative pagination values.

cruxible source get

Usage: cruxible source get [OPTIONS] SOURCE_ARTIFACT_ID

Purpose: Read a registered source artifact's metadata and chunk map.

Options And Arguments:

Name	Required	Default	Type	Description
SOURCE_ARTIFACT_ID	yes	Sentinel.UNSET	text	Source artifact ID returned by source register.
--chunks / --no-chunks	no	True	boolean	Show or hide the chunk metadata table in human output.
--json	no	False	boolean	Output the full read contract payload as JSON, including chunk text when available.

Output And Side Effects: - Read-only. Human output renders an artifact header with id, immutable revision id and handle, kind, label, original URI, retention, and content availability; when content is unavailable, the reason is shown. - By default, human output also renders a chunk table with chunk id, citation handle, heading path, block type, and line range. It does not print full chunk text; use --json or source dereference when source body text is needed. - With --json, emits the full SourceArtifactReadResult contract payload.

Common Errors: - Missing local instance or stale daemon --instance-id. - Permission mode too low for source artifact reads. - Unknown source artifact ID.

cruxible source register

Usage: cruxible source register [OPTIONS]

Purpose: Register a Markdown document as source-backed proposal evidence.

Options And Arguments:

Name	Required	Default	Type	Description
--path	yes	Sentinel.UNSET	text	Local Markdown source path. Relative paths resolve from the current workspace.
--id	no	``	text	Caller-supplied deterministic artifact id (3-64 chars of [A-Za-z0-9._-], alphanumeric start); duplicates are refused. Omit for a generated SRC-* id.
--kind	no	markdown	choice	Source parser kind.
--retention	no	manifest_only	choice	Source retention mode: manifest_only or archive.
--original-uri	no	``	text	Optional display/provenance URI to preserve in the manifest.
--label	no	``	text	Optional display label.
--json	no	False	boolean	Output the registered artifact and chunk manifest as JSON.

Examples:

cruxible source register \
  --path docs/vendor-evidence.md \
  --original-uri https://vendor.example/evidence.md \
  --label "Vendor evidence" \
  --json

cruxible source register \
  --path docs/vendor-evidence.md \
  --retention archive

Output And Side Effects: - Persists a source artifact ID, document hash, parser version, byte count, and deterministic chunk IDs in state.db. - Returns a revision handle (src1_...) plus one chunk citation handle (cite1_...) per chunk. These are derived, not stored in a mutable registry. - With manifest_only, Cruxible stores the manifest and local path but not a deep copy of the source bytes. - With archive, Cruxible also stores the source bytes so later dereference can use the archived body if the local file is missing or changed.

Common Errors: - Missing source path, unsupported source kind, path outside the registered workspace in daemon mode, or unreadable source file.

cruxible source dereference

Usage: cruxible source dereference [OPTIONS]

Purpose: Resolve a registered source-evidence locator back to source text.

Options And Arguments:

Name	Required	Default	Type	Description
--artifact	yes	Sentinel.UNSET	text	Source artifact ID returned by source register.
--revision	no	``	text	Pin the read to one immutable revision ({artifact}@{n}). Omit to read the current revision, which is reported as revision_unpinned.
--chunk	no	``	text	Deterministic chunk ID from the registered manifest.
--heading	no	``	text	Heading path segment. Repeat for nested headings.
--block-selector	no	``	text	Block selector under the heading path, such as paragraph:1.
--expected-content-hash	no	``	text	Optional expected chunk content hash for drift checks.
--json	no	False	boolean	Output dereference status, chunk metadata, and body as JSON.

Source-evidence locators must use one of two forms:

• --chunk <chunk-id>
• --heading <heading> [--heading <nested-heading> ...] --block-selector <selector>

Examples:

cruxible source dereference \
  --artifact SRC-... \
  --chunk CHK-... \
  --json

cruxible source dereference \
  --artifact SRC-... \
  --heading "Compatibility Evidence" \
  --block-selector paragraph:1

Output And Side Effects: - Read-only. Returns available, drifted, unavailable, or revision_bytes_not_retained plus source body when Cruxible can safely dereference the locator. - revision_bytes_not_retained means the pinned revision has been superseded and its bytes were never archived: the local file now holds a NEWER revision, so Cruxible refuses to call the guaranteed hash mismatch drift. - body_origin is archive when archived bytes are used, or local_path when Cruxible rereads the registered local file.

Common Errors: - Missing artifact, incomplete locator, unknown chunk, unavailable local source file for manifest_only, or content drift against the stored manifest/hash.

cruxible stats

Usage: cruxible stats [OPTIONS]

Purpose: Display entity and relationship counts for this instance.

Options And Arguments:

Name	Required	Default	Type	Description
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible telemetry

Usage: cruxible telemetry [OPTIONS]

Purpose: Inspect aggregate traffic crossing core-owned surfaces.

Subcommands:

• cruxible telemetry summary - Show per-surface call, error, payload-byte, and duration counters.

Output And Side Effects: - Read-only output unless the command records an explicit receipt, feedback, outcome, or decision event.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible telemetry summary

Usage: cruxible telemetry summary [OPTIONS]

Purpose: Show per-surface call, error, payload-byte, and duration counters.

Options And Arguments:

Name	Required	Default	Type	Description
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only. Prints the earliest recorded timestamp, then one line per surface with call count, error count, total response bytes, and total/maximum duration in milliseconds. - Surface names carry their boundary: an HTTP route name (stats), an MCP tool name (cruxible_stats), a locally invoked service verb (service_stats), or a whole CLI command (cli:stats). A CLI command's emitted bytes and wall time belong to its cli: row; each service verb keeps its own measured duration. - Counters are aggregated in memory and written by a background flusher; this read flushes the instance first, so it never lags the calls it summarizes.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible test

Usage: cruxible test [OPTIONS]

Purpose: Execute config-defined workflow tests for the current instance.

Options And Arguments:

Name	Required	Default	Type	Description
--name	no	``	text	Run only a named workflow test.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible validate

Usage: cruxible validate [OPTIONS]

Purpose: Validate a config YAML file without creating an instance.

Options And Arguments:

Name	Required	Default	Type	Description
--config	yes	Sentinel.UNSET	text	Path to config YAML file.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible instance

Usage: cruxible instance [OPTIONS]

Purpose: Back up and restore exact Cruxible instances.

Subcommands:

• cruxible instance backup - Write a portable same-identity backup artifact for the current instance.
• cruxible instance restore - Restore a same-identity backup artifact.
• cruxible instance relocate - Move the current healthy instance to a new directory, preserving identity.

Output And Side Effects: - Command-specific output only.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible instance backup

Usage: cruxible instance backup [OPTIONS] ARTIFACT_PATH

Purpose: Write a portable same-identity backup artifact for the current instance.

Options And Arguments:

Name	Required	Default	Type	Description
ARTIFACT_PATH	yes		path	Destination path for the backup artifact.
--label	no		text	Optional human label for the backup artifact.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Writes a portable same-identity backup artifact (including the authoritative state database) for the current instance. Requires ADMIN.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible instance restore

Usage: cruxible instance restore [OPTIONS] ARTIFACT_PATH

Purpose: Restore a same-identity backup artifact.

Options And Arguments:

Name	Required	Default	Type	Description
ARTIFACT_PATH	yes		path	Backup artifact to restore from.
--at	no		text	Restore target root directory.
--activate / --no-activate	no		boolean	Make the restored server instance the active CLI context instance.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Restores a daemon-backed instance from a same-identity backup artifact. Requires ADMIN.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible instance relocate

Usage: cruxible instance relocate [OPTIONS]

Purpose: Move the current healthy instance to a new directory, preserving identity.

Options And Arguments:

Name	Required	Default	Type	Description
--to	yes		text	New root directory for the instance.
--remove-source / --keep-source	no	keep-source	boolean	Delete the old directory after a successful relocate (default: keep it).
--activate / --no-activate	no		boolean	Make the relocated server instance the active CLI context instance.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Moves a healthy daemon-backed instance to a new directory while preserving its identity; the registry is repointed to the new location. Requires ADMIN.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible state

Usage: cruxible state [OPTIONS]

Purpose: Compare, publish, and track state across coordinates.

Subcommands:

• cruxible state create-overlay - Create a new local overlay instance from a published state release.
• cruxible state diff - Diff state between two coordinates (snapshot, current, upstream, origin).
• cruxible state health - Show read-only deterministic state-health maintenance signals.
• cruxible state publish - Publish the current root state-model instance as an immutable release bundle.
• cruxible state pull-apply - Apply a previewed upstream release into the current overlay.
• cruxible state pull-preview - Preview pulling a newer upstream release into the current overlay.
• cruxible state status - Show upstream tracking metadata for the current instance.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible state create-overlay

Usage: cruxible state create-overlay [OPTIONS]

Purpose: Create a new local overlay instance from a published state release.

Options And Arguments:

Name	Required	Default	Type	Description
--transport-ref	no	Sentinel.UNSET	text	Transport ref, e.g. file://... or oci://...
--state-ref	no	Sentinel.UNSET	text	State alias, e.g. kev-reference or kev-reference@2026-03-27.
--kit	no	Sentinel.UNSET	text	Apply a checked-in local overlay kit, e.g. kev-triage.
--no-kit	no	False	boolean	Skip automatic kit application and create a bare overlay.
--root-dir	no	``	text	Workspace root for the new overlay (defaults to current directory in server mode).
--activate / --no-activate	no	True	boolean	Make the new server overlay the active CLI context instance.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible state diff

Usage: cruxible state diff [OPTIONS] [FROM_COORDINATE] [TO_COORDINATE]

Purpose: Diff state between two coordinates.

A coordinate is current, a snapshot id (snap_ plus 16 hex characters, exactly as cruxible snapshot list prints it), upstream (the verified materialized tracked release), or origin (clone provenance; absent on an init-created instance). A release you have not pulled is deliberately NOT a coordinate — cruxible state pull-preview owns transport and foreign-byte verification; once materialized it becomes upstream here.

With no arguments the diff is parent-of-head to current, and the result stamps default_basis. commit_graph_snapshot persists a snapshot AND advances live state in one boundary, so head-to-current would be the empty diff by construction on exactly the instances someone would run this on; the fallback when head has no parent is head-to-current, and it says so.

Options And Arguments:

Name	Required	Default	Type	Description
FROM_COORDINATE	no	``	text	Left coordinate; defaults to the parent of the head snapshot.
TO_COORDINATE	no	current	text	Right coordinate. added means present here only.
--section	no	``	choice	Restrict the diff to these sections (repeatable).
--entity-type	no	``	text	Restrict entities to these types.
--relationship-type	no	``	text	Restrict edges to these relationship types.
--bucket	no	``	choice	Report only these buckets (counts stay whole).
--changed-only	no	False	boolean	Suppress added/removed items.
--max-items	no	500	integer	Per-bucket cap for the returned view; the persisted artifact is never capped.
--artifact	no	``	text	Re-read a persisted diff artifact by its diff_digest instead of computing one.
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only with respect to graph state, but NOT side-effect-free: every diff persists a receipt (operation_type="state_diff", carrying both coordinates and the diff_digest in parameters) and writes the complete canonical artifact, content-addressed, under .cruxible/diffs/. Both persistence failures fail the read. Artifacts are not garbage-collected. - The returned body is BOUNDED (per-bucket caps, property values over 2KB elided with {elided, value_digest, byte_count}); diff_digest always covers the complete unelided body, view_digest covers the bounded bytes, and only an artifact_complete: true result may be treated as a reviewed plan. - Live-view membership is never evaluated (liveness: "not_evaluated"): computing it would make the digest depend on the clock.

Common Errors: - Unknown snapshot id, or a snapshot missing/corrupt graph.json. - upstream on an instance that is not a pullable overlay, or a tracked upstream member that was pinned and no longer matches. - origin on an instance that was never cloned; a bare diff on an instance with no snapshots. - Concurrent current drift after one retry.

cruxible state health

Usage: cruxible state health [OPTIONS]

Purpose: Show read-only deterministic state-health maintenance signals.

Options And Arguments:

Name	Required	Default	Type	Description
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only. Aggregates deterministic maintenance signals (group counts/ages, edge provenance tally, source-artifact/provider-trace freshness, config-compatibility, and graph-integrity counts) into four sections. Reports raw metrics and binary deterministic facts only; no scoring, ranking, severity, or thresholds. Creates no receipts and mutates nothing.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible state publish

Usage: cruxible state publish [OPTIONS]

Purpose: Publish the current root state-model instance as an immutable release bundle.

Options And Arguments:

Name	Required	Default	Type	Description
--transport-ref	yes	Sentinel.UNSET	text	Transport ref, e.g. file://... or oci://...
--state-id	yes	Sentinel.UNSET	text	Stable published state identifier.
--release-id	yes	Sentinel.UNSET	text	User-supplied release identifier.
--compatibility	no	data_only	choice	Compatibility classification for the published release.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible state pull-apply

Usage: cruxible state pull-apply [OPTIONS]

Purpose: Apply a previewed upstream release into the current overlay.

Options And Arguments:

Name	Required	Default	Type	Description
--apply-digest	yes	Sentinel.UNSET	text	Apply digest returned by pull-preview.
--repair	no	False	boolean	Repair mode: re-apply the release ALREADY tracked, to restore a materialized upstream that was damaged locally. Normally refused as a no-op; the local copy's digest verification is skipped because that is the check the damage trips. Claim ids are preserved.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible state pull-preview

Usage: cruxible state pull-preview [OPTIONS]

Purpose: Preview pulling a newer upstream release into the current overlay.

Options And Arguments:

Name	Required	Default	Type	Description
--repair	no	False	boolean	Repair mode: re-apply the release ALREADY tracked, to restore a materialized upstream that was damaged locally. Normally refused as a no-op; the local copy's digest verification is skipped because that is the check the damage trips. Claim ids are preserved.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible state status

Usage: cruxible state status [OPTIONS]

Purpose: Show upstream tracking metadata for the current instance.

Output And Side Effects: - Calls the service layer and may create receipts, traces, snapshots, config changes, groups, or graph mutations depending on the command.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - Permission mode too low for mutations or admin operations. - Unknown config/workflow/query/entity names, or stale workflow locks where applicable.

cruxible ws

Usage: cruxible ws [OPTIONS] COMMAND [ARGS]...

Purpose: Agent-local working set: opt-in, NON-AUTHORITATIVE read cache.

An opt-in prototype (acceptance is gated on the RuneBench pilot). When enabled — CRUXIBLE_WORKING_SET=1 in the environment, or --ws on a supported --json read (query run, entity get, entity inspect, relationship get, list entities, list edges, sample) — every entity or edge those reads return is ALSO appended, normalized through the compact profile serializer, to <working-set root>/<instance-key>/records.jsonl. The root defaults to ~/.cruxible/working-set and can be redirected with CRUXIBLE_WORKING_SET_DIR (precedence: explicit env > default home dir). That same variable opts the co-located MCP server's read tools into capture (see the Working-Set Capture section of docs/mcp-tools.md), and every cruxible ws verb resolves paths through it — so this group manages an MCP-rooted cache too. In authenticated server mode the instance key is credential-scoped — <instance-id>-cred-<scope>, where the scope is a salted hash of the bearer credential (random salt persisted once at <working-set root>/.scope-salt, mode 0600; no token material is ever written) — so different credentials on the same host never share records. Tokenless server mode uses the bare instance id; local mode uses a hash of the resolved instance root (per-OS-user via ~). Re-finding something then costs a grep instead of a re-query: rg BP-1001 "$(cruxible ws path)".

Cache contract: - Line 1 of every file is a #-prefixed header marking the cache NON-AUTHORITATIVE; jq/rg users skip it naturally. - One JSON object per line: kind (entity|edge), identity fields, props (compact-profile slice), lifecycle, review, read_revision (null = unverifiable, reported as unknown by ws verify), config_digest (the active config digest at capture time; missing digests are classified unknown, never fresh), as_of, receipt_refs, source_cmd. - Appends dedupe by identity: newest read_revision wins, ties go to the latest as_of. - The reader validates every line against the record shape: corrupt or wrong-shaped lines are skipped with a stderr warning and counted (invalid_lines in ws status, invalid in ws verify) — never a crash, and never classified as fresh. - The cache is NEVER read by any write path or any other CLI command; capture and this command group are the only code that touches it. Capture never changes the read's stdout — it is a pure side effect.

File hygiene and tamper honesty: - Working-set directories (the configured root AND each instance directory) are created mode 0700 and records files mode 0600, and all of them are idempotently re-tightened on every write touch, so pre-existing lax-mode caches heal on next use; ancestors above the configured root are never chmodded. - Every verb — capture and ws status/verify/refresh/clear — validates the full path chain (configured root, instance directory, records file, and the scope-salt file where applicable) with lstat/O_NOFOLLOW discipline BEFORE its first read, stat, write, or unlink: a symlink at ANY level, including a symlinked CRUXIBLE_WORKING_SET_DIR root, is refused outright — capture with a stderr warning (the read itself is unaffected), the ws verbs with a usage error. - The cache files are SAME-USER-WRITABLE BY DESIGN: any process running as the same OS user can rewrite records undetected. The hygiene above reduces accidents and cross-user exposure — it is NOT a defense against a same-user adversary. Tamper-evidence would require a daemon-signed record mechanism (a possible future addition, deliberately not implemented). Treat records as hints to re-verify (cruxible ws verify), never proof.

Subcommands:

Command	Purpose
path	Print the records file path for the current context.
status	Record counts, file size, cached-vs-current revision spread.
verify	Classify records fresh/stale/unknown against the live revision AND active config digest.
refresh	Re-fetch stale records; drop deleted targets.
clear	Delete the current context's records file.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - No local .cruxible/ instance found (local mode).

cruxible ws path

Usage: cruxible ws path [OPTIONS]

Purpose: Print the records file path for the current context (for rg/jq).

Output And Side Effects: - Read-only; prints the path whether or not the file exists yet.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - No local .cruxible/ instance found (local mode).

cruxible ws status

Usage: cruxible ws status [OPTIONS]

Purpose: Show record counts, file size, and cached-vs-current revision spread.

Options And Arguments:

Name	Required	Default	Type	Description
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only. Reports the instance key, records file path and size, record counts by kind and by entity/relationship type, the count of invalid lines skipped by the validating reader (invalid_lines), and the current instance read revision versus the newest/oldest cached revisions. - Fetches the current read revision (stats endpoint in server mode, the local instance otherwise); corrupt or wrong-shaped cache lines are skipped with a stderr warning and counted, never a crash.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - No local .cruxible/ instance found (local mode).

cruxible ws enable

Usage: cruxible ws enable [OPTIONS]

Purpose: Persistently enable working-set capture.

Output And Side Effects: - Writes working_set: true into the persisted CLI context (~/.cruxible/client-context.json), so every later --json read captures without needing --ws or CRUXIBLE_WORKING_SET. Transport fields in the context (server URL/socket, instance id) are preserved untouched. - Activation precedence stays: explicit --ws flag, then a set CRUXIBLE_WORKING_SET environment variable (a present-but-false value overrides a persisted enable), then this persisted preference.

Common Errors: - Unreadable or malformed CLI context file.

cruxible ws disable

Usage: cruxible ws disable [OPTIONS]

Purpose: Persistently disable working-set capture.

Output And Side Effects: - Writes working_set: false into the persisted CLI context; --ws or the environment variable can still enable capture per invocation. Transport fields are preserved untouched.

Common Errors: - Unreadable or malformed CLI context file.

cruxible ws catalog

Usage: cruxible ws catalog [OPTIONS]

Options And Arguments:

Name	Required	Default	Type	Description
--json	no	False	boolean	Output as JSON.

Purpose: Regenerate the control-plane catalog from the active config.

Output And Side Effects: - Rewrites catalog.jsonl (sibling of records.jsonl) atomically: a complete, bounded, deterministic index of the instance's control plane — entity types with property names, relationship types with endpoints and write policy, named queries with params/returns, and governed procedures (id, name, status, version, summary) — one JSON object per line under a # header stamped with the active config digest. - Unlike records.jsonl (partial, interest-driven), the catalog is total for the control plane and is never appended to during capture; ws refresh also regenerates it. Config-declared elements come from the loaded instance config (local) or the same schema surface cruxible schema uses (server); procedures are state-held records and are paged from the same list surface cruxible procedure list uses. If the procedure listing fails (e.g. an older daemon), the catalog regenerates its config-derived entries with a stderr warning and zero procedure lines. - Prints entry counts by kind and the file path.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - No local .cruxible/ instance found (local mode).

cruxible ws verify

Usage: cruxible ws verify [OPTIONS]

Purpose: Verify cached records against the current instance read revision and active config digest.

Options And Arguments:

Name	Required	Default	Type	Description
--json	no	False	boolean	Output as JSON.

Output And Side Effects: - Read-only. Classifies every cached record: fresh (cached read_revision equals the current instance revision AND the cached config_digest concretely matches the active config), stale (any other concrete revision, or a config-digest mismatch — reported as "config changed"), unknown (no revision or no config digest recorded, or the CURRENT config digest is unresolvable — honest freshness: a record is never fresh unless both axes were actually compared). Malformed/wrong-shaped lines are reported separately as invalid — skipped by the reader, never fresh. - Script-friendly exit contract: 0 when every record is fresh or unknown AND no lines are invalid; 1 when any record is stale OR any invalid lines are present — a tampered/corrupt cache must be loud in scripts. Unknown records alone never fail verification.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - No local .cruxible/ instance found (local mode).

cruxible ws refresh

Usage: cruxible ws refresh [OPTIONS]

Purpose: Regenerate the catalog; re-fetch stale/unknown captured records.

Output And Side Effects: - Regenerates catalog.jsonl from the active config first (see cruxible ws catalog), then refreshes captured records. - Entities are re-read via the compact get-entity read; edges via the owning (from-side) entity's bounded neighborhood inspect, scoped to the edge's relationship type. Fresh records are left byte-identical. - Records whose target is gone (entity deleted, edge removed or no longer live, owning entity deleted) are dropped with a note. Records that cannot be confirmed (fetch error, truncated neighborhood) are kept and counted as failed. The file is rewritten atomically and reports refreshed/removed/failed counts.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - No local .cruxible/ instance found (local mode).

cruxible ws clear

Usage: cruxible ws clear [OPTIONS]

Purpose: Delete the current context's records and catalog files.

Output And Side Effects: - Deletes only the current context's records.jsonl and catalog.jsonl; refuses any path that resolves outside the working-set root (hostile instance keys are rejected before any filesystem access) and refuses a symlink at any path-chain level (configured root, instance directory, target file) outright.

Common Errors: - Missing or stale --instance-id for daemon-backed commands. - No local .cruxible/ instance found (local mode).