CLI Reference

Overview

The jacqos CLI is a single binary that handles scaffolding, development, live observation append, effect-authoritative runs, verification, export, and operational tasks. Every command works locally — no cloud dependency, no hosted coordination.

jacqos <COMMAND> [OPTIONS]

Stability. Every command and flag documented on this page is part of the V1 stable surface. See V1 Stability and Upgrade Promises for what JacqOS guarantees, what can change in V1.x, and what requires a V2 boundary.

jacqos scaffold

Creates a new JacqOS application with the standard directory structure. Use --agents <NAMES> when you want a multi-agent starting point with namespace-separated ontology files and golden fixtures that already exercise cross-agent coordination through the shared model. Use --pattern to start from a single-namespace scaffold pre-wired for the relay pattern your first rule will use.

jacqos scaffold <APP_NAME> [--agents <NAMES>] [--pattern <PATTERN>]

Arguments and options:

Parameter	Required	Description
APP_NAME	Yes	Name of the application to create
--agents <NAMES>	No	Scaffold a namespace-partitioned multi-agent app. NAMES is a comma-separated list of at least two lowercase namespaces such as infra,triage,remediation
--pattern <PATTERN>	No	Pattern-aware scaffold. sensor emits a candidate.* starter; decision emits a proposal.* starter. Conflicts with --agents

Example:

jacqos scaffold my-booking-app

# Start from a namespace-partitioned multi-agent shape
jacqos scaffold incident-response --agents infra,triage,remediation

# Start from a sensor scaffold pre-wired for the candidate.* relay
jacqos scaffold doorbell --pattern sensor

# Start from a decision scaffold pre-wired for the proposal.* relay
jacqos scaffold triage --pattern decision

Creates the scaffolded app shape:

my-booking-app/
  jacqos.toml
  ontology/
    schema.dh
    rules.dh
    intents.dh
  mappings/
    inbound.rhai
  helpers/
    normalize.rhai
  prompts/
  schemas/
  fixtures/
    happy-path.jsonl

With --agents, the scaffold is partitioned for independent agent-owned rule domains:

incident-response/
  jacqos.toml
  ontology/
    schema.dh
    intents.dh
    invariants.dh
    infra/
      rules.dh
    triage/
      rules.dh
    remediation/
      rules.dh
  mappings/
    inbound.rhai
  fixtures/
    happy-path.jsonl
    happy-path.expected.json
    contradiction-path.jsonl
    contradiction-path.expected.json

The generated namespaces compose in order: the first namespace reads from atom(), each later namespace reads from the shared derived state established earlier, intent.* stays at the world boundary, and invariants.dh makes the cross-namespace contract explicit from day one.

jacqos dev

Starts a development session with hot-reload and an inspection API server.

jacqos dev

The dev server watches your .dh, .rhai, and other source files. When you save a change, the evaluator reloads in under 250ms — no compilation step. The inspection API lets Studio connect for the drill inspector, timeline, and ontology browser.

Reload behavior:

Change	Effect	Speed
.dh ontology change	Re-derive facts from existing atoms	<250ms
.rhai mapper change	Regenerate atoms, then re-derive facts	Proportional to observation count
.rhai helper change	New evaluator digest, full rebuild	<250ms for small corpora
jacqos.toml change	Full reload	<250ms

jacqos serve

Starts the local HTTP and SSE runtime for adapters, Studio live mode, and other local clients. serve uses the same commandable core as observe, run, activation, and lineage commands. It does not introduce a second truth surface: every command still appends observations, evaluates a lineage, promotes an activation, or reads durable store projections.

jacqos serve [--host <IP_OR_LOCALHOST>] [--port <PORT>] [--allow-non-loopback] [--auth-token-env <ENV>] [--json]

Options:

Option	Description
--host <IP_OR_LOCALHOST>	Bind address. Defaults to 127.0.0.1
--port <PORT>	Bind port. Defaults to 8787
--allow-non-loopback	Allow binding to a non-loopback address
--auth-token-env <ENV>	Read a bearer token from an environment variable
--json	Print the serve receipt as JSON

Loopback is the default security boundary. Binding to a non-loopback address requires both --allow-non-loopback and --auth-token-env; unauthenticated requests are rejected. Serve responses are rendered through the same redaction policy used for provider credentials, and the bearer token is also redacted from error responses.

The serve receipt includes the app id, listen address, whether auth is required, inspection protocol metadata, and the Phase A/B retention stance. The retention stance is explicit: JacqOS performs no automatic GC of observations, provider captures, attempt reports, run invocation records, lineage event rows, or idempotency rows. lineage_events retention is durable and unbounded until an explicit GC policy exists.

Status and inspection endpoints:

Method	Path	Meaning
GET	/healthz	Minimal health response
GET	/v1/status	Serve receipt, security defaults, inspection metadata, retention stance
GET	/v1/inspection	Existing Studio inspection descriptor when a dev/inspection server is active

Command endpoints:

Method	Path	Meaning
POST	/v1/lineages	Create a lineage from { "lineage_id": "..." }
POST	/v1/lineages/{lineage_id}/observations	Append one observation. Body matches jacqos observe fields: kind, payload, source, optional timestamp, observation ref, idempotency fields, and create_lineage
POST	/v1/lineages/{lineage_id}/observation-batches	Append JSONL or an observations array in order
POST	/v1/lineages/{lineage_id}/run	Run the lineage with effect_mode, once, until, max_rounds, and max_effects
POST	/v1/lineages/{lineage_id}/forks	Fork the lineage, optionally at fork_head
PUT	/v1/lineages/{lineage_id}/activation	Promote the loaded evaluator/package for the lineage

Adapter endpoints:

Method	Path	Meaning
POST	/v1/adapters/chat/sessions/{session_id}/messages	Append a chat.user_message observation to lineage chat:{session_id}, run the lineage, and return accepted chat.assistant_message projections with provenance URLs
POST	/v1/adapters/webhooks/{adapter_id}/deliveries	Validate a signed delivery before append, write to lineage webhook:{adapter_id}:{lineage_key}, run the lineage, and return the observation/run receipts

The adapter endpoints are not separate runtimes. They are wrappers over append, run, query, and SSE. The chat adapter auto-creates only chat: lineages and uses chat:{session_id}:{message_id} as the default idempotency key. The webhook adapter auto-creates only webhook: lineages, validates signature before writing any observation, and returns webhook.signature_invalid without mutating the store when validation fails.

POST /run enforces one active run per lineage. If another run is already active, the server returns run.concurrent with the active run_id. Runs on independent lineages may proceed concurrently.

Query endpoints:

Method	Path	Meaning
GET	/v1/lineages	List lineages
GET	/v1/lineages/{lineage_id}	Read one lineage record
GET	/v1/lineages/{lineage_id}/status	Read lineage head, activation, active run id, recent run records, and serve metadata
GET	/v1/lineages/{lineage_id}/observations?from_head=N	Read observations after a head, or all observations when omitted
GET	/v1/lineages/{lineage_id}/facts?relation=R	Read fact-plane entries for the committed activation or latest run evaluator
GET	/v1/lineages/{lineage_id}/intents?relation=R	Read intent-plane entries for the committed activation or latest run evaluator
GET	/v1/lineages/{lineage_id}/effects	Read effect requests, attempts, and attempt reports
GET	/v1/lineages/{lineage_id}/runs	List run invocation records
GET	/v1/lineages/{lineage_id}/runs/{run_id}	Read one run invocation record
GET	/v1/lineages/{lineage_id}/activation	Read the committed activation
GET	/v1/lineages/{lineage_id}/provenance?...	Extract a provenance neighborhood from fact_id, intent_fact_id, contradiction_id, violation_id, observation_ref, or seed_kind plus seed_id

Fact, intent, and effect queries accept evaluator_digest when you need an explicit evaluator. Without it, the server uses the committed activation for the lineage, then falls back to the latest run invocation. If neither exists, the query returns evaluator.unavailable.

SSE event stream:

GET /v1/lineages/{lineage_id}/events?since_event=12
GET /v1/lineages/{lineage_id}/events?since=head:42&relation=agent.alert

The stream uses text/event-stream, SSE id: <event_id>, and event names such as observation.appended, evaluation.completed, fact.delta, intent.admitted, effect.started, effect.succeeded, effect.failed, effect.blocked, reconciliation.required, run.completed, run.failed, run.warning, stream.backpressure, and stream.resume_window_exceeded.

Resume behavior:

• ?since_event=<event_id> resumes from durable lineage_events.
• Last-Event-ID has the same meaning when since_event is omitted.
• ?since=head:N returns events with observation heads after N where they are available from the durable event projection.
• ?relation=<RELATION> filters relation-bearing events such as fact.delta, intent.admitted, and effect events.
• ?event_type=<TYPE> filters by SSE event name.
• ?limit=<N> caps the catch-up response. If more events are available, the server emits stream.backpressure and closes the response so the client can reconnect with the last event id it processed.

If a future explicit retention policy removes the requested event window, the server emits stream.resume_window_exceeded instead of pretending the resumed stream is complete. In Phase A/B, event retention is durable and unbounded by default.

Studio live mode:

Studio can read the same serve surfaces by setting JACQOS_STUDIO_SERVE_URL=http://127.0.0.1:8787. Set JACQOS_STUDIO_LINEAGE to choose a lineage and JACQOS_STUDIO_SERVE_TOKEN when the serve process requires bearer auth. In serve mode, Studio reads lineage status, observation tail, fact and intent deltas, effects, run records, provenance, invariant/contradiction evidence, and reconciliation.required events from the public query and event endpoints.

jacqos observe

Appends live observations to a lineage. Use this when you want to exercise the same observation-first pipeline as fixture replay, but from command-line input.

jacqos observe --kind <KIND> --payload <JSON> --source <SOURCE> [OPTIONS]
jacqos observe --jsonl <PATH> [OPTIONS]

Options:

Option	Description
--kind <KIND>	Observation kind for a single append. Required unless --jsonl is used
--payload <JSON>	Inline JSON payload for a single append
--payload-file <PATH>	Read the single-observation payload from a file
--jsonl <PATH>	Append an observation JSONL file in order
--source <SOURCE>	Producer label for a single append. Required unless --jsonl is used
--lineage <LINEAGE>	Append to a specific lineage. Defaults to default
--create-lineage	Create the lineage if it does not already exist
--timestamp <TIME>	Override the observation timestamp
--idempotency-key <KEY>	Make the append idempotent for retrying the same ingress event
--json	Print the append receipt as JSON

Examples:

jacqos observe \
  --kind intake.submitted \
  --payload '{"id":"intake-1","raw":"patient reports a cough"}' \
  --source cli \
  --json

jacqos observe --jsonl fixtures/happy-path.jsonl --lineage scratch --create-lineage --json

The JSON receipt includes the observation_address, observation_id, observation reference, resulting head, and whether an idempotency key replayed an existing append. A JSONL append preserves fixture order, which is why jacqos observe --jsonl ... plus a shadow jacqos run can be compared directly with jacqos replay.

jacqos activation

Shows or promotes the evaluator package that is allowed to execute effects for a lineage.

jacqos activation show [--lineage <LINEAGE>] [--json]
jacqos activation promote [--lineage <LINEAGE>] [--select-for-live] [--reason <TEXT>] [--json]

Options:

Option	Description
--lineage <LINEAGE>	Activation lineage. Defaults to default
--select-for-live	Mark the promoted activation as the selected live activation
--reason <TEXT>	Store operator-readable promotion context
--json	Print the activation receipt as JSON

Examples:

jacqos activation show --json
jacqos activation promote --reason "verified happy path and egress policy" --json

Effect authority is scoped to the pair of lineage_id plus the current evaluator and package digests. A shadow build may derive facts and intents, but it cannot execute effects until you promote the matching activation for that lineage.

jacqos run

Evaluates the current lineage and, when effect authority allows it, advances ready effects.

jacqos run [--once | --until quiescent] [--lineage <LINEAGE>] [--shadow | --require-effect-authority] [OPTIONS]

Options:

Option	Description
--once	Run one evaluation/effect-advancement round
--until quiescent	Continue rounds until no ready work remains. This is the default when --once is omitted
--lineage <LINEAGE>	Run a specific lineage. Defaults to default
--shadow	Evaluate and report without executing effects
--require-effect-authority	Fail unless the current evaluator/package is the committed activation for the lineage
--max-rounds <N>	Cap --until quiescent loops. Defaults to 10
--max-effects <N>	Cap effect attempts in one run. Defaults to 20
--json	Print the run receipt as JSON

Examples:

# Prove the current derived world without touching external systems
jacqos run --once --shadow --json

# Execute effects only after promoting the matching activation
jacqos activation promote --reason "fixtures verified" --json
jacqos run --until quiescent --json

# Turn authority drift into a hard failure instead of a shadow warning
jacqos run --require-effect-authority --json

Without --shadow or --require-effect-authority, jacqos run uses prefer_committed_activation: it executes effects only when the loaded evaluator and package match the committed activation. If no matching activation exists, the command completes in shadow_complete with an authority.shadow_mode warning and starts no effect attempts.

Run receipts include the lineage, run id, from/to observation heads, worldview identity, world_digest, resolved effect-authority mode, attempted effect count, appended observation count, terminal status, and warnings. Important statuses include:

Status	Meaning
quiescent	No ready work remains after the run
shadow_complete	The run evaluated without effect execution
blocked	An invariant, contradiction, authority boundary, egress policy, or reconciliation boundary blocked progress
idle_pending_timers	Only future timer effects remain
idle_pending_retries	Only future retry attempts remain
reconciliation_required	A non-idempotent or ambiguous attempt needs explicit reconciliation
max_rounds_exceeded	The run hit --max-rounds before quiescence
max_effects_exceeded	The run hit --max-effects before quiescence

Live http.fetch effects pass through the configured egress boundary before transport dispatch. Private/local destinations are blocked with http.egress.private_ip_denied; non-allowlisted hosts are blocked with http.egress.allowlist_denied. These appear as blocked effect requests, not as successful provider receipts.

For deterministic parity, use this shape:

jacqos replay fixtures/happy-path.jsonl

jacqos observe --jsonl fixtures/happy-path.jsonl --lineage scratch --create-lineage --json
jacqos run --once --shadow --lineage scratch --json
jacqos export facts --lineage scratch

The shadow live run and the fixture replay should produce the same world_digest when the same observations are evaluated by the same evaluator.

jacqos replay

Replays an evaluation against a named fixture.

jacqos replay [--lineage <LINEAGE>] <FIXTURE>

Arguments and options:

Parameter	Required	Description
FIXTURE	Yes	Fixture name to replay (for example fixtures/happy-path.jsonl)
--lineage <LINEAGE>	No	Replay into a specific lineage instead of default

Example:

jacqos replay fixtures/happy-path.jsonl

# Replay into a forked child lineage
jacqos replay --lineage child-01 fixtures/double-booking-path.jsonl

Replay feeds the fixture’s observations through the mapper and evaluator in order, producing the full derived state. Replay-only effects use recorded provider captures instead of making live calls. The output shows derived facts, fired intents, and any invariant violations. Use --lineage when you want to continue a child branch without mutating the parent lineage.

See Golden Fixtures for how fixtures work and Fixtures and Invariants for writing them.

jacqos shrink-fixture

Reduces a failing fixture to a minimal reproducer. Useful when a long generated timeline trips an invariant — shrinking strips out everything that is not load-bearing for the failure so you can review and check the shrunk fixture into your corpus.

jacqos shrink-fixture <FIXTURE> [--output <PATH>]

Arguments and options:

Parameter	Required	Description
FIXTURE	Yes	Path to the fixture to shrink (jsonl)
--output <PATH>	No	Write the shrunk fixture to this path. Defaults to generated/shrunk-fixtures/<fixture>-<failure>-<hash>.jsonl

Example:

# Write a minimized fixture under generated/shrunk-fixtures/ and print a JSON report
jacqos shrink-fixture fixtures/generated-counter-001.jsonl

# Save the shrunk fixture next to the original
jacqos shrink-fixture fixtures/generated-counter-001.jsonl \
  --output fixtures/counter-no_double_book-001.jsonl

jacqos fixture

Authoring helpers for the golden-fixture loop. These commands do not replace jacqos verify; they make it easier to create scenarios, promote minimized counterexamples, and review expected-world diffs before committing fixtures.

jacqos fixture template

Creates a starter fixture and matching .expected.json skeleton.

jacqos fixture template <KIND> <NAME> [--output <PATH>] [--force]

Arguments and options:

Parameter	Required	Description
KIND	Yes	One of happy-path, contradiction-path, policy-bypass, human-review, multi-agent
NAME	Yes	Scenario name. Used for the default filename and authoring metadata
--output <PATH>	No	Write the fixture to this path. Defaults to fixtures/<name>.jsonl
--force	No	Overwrite an existing fixture or expectation file

jacqos fixture template policy-bypass refund-threshold
jacqos fixture template human-review clinical-escalation \
  --output fixtures/clinical-escalation.jsonl

The generated observations are intentionally generic. Replace them with domain observations your mapper understands, then fill the expected facts, intents, contradictions, and invariant violations in the generated .expected.json file.

jacqos fixture promote-counterexample

Copies a generated or shrunk counterexample into the checked-in fixture corpus and writes a matching expectation skeleton.

jacqos fixture promote-counterexample <COUNTEREXAMPLE> <NAME> [--output <PATH>] [--force]

jacqos fixture promote-counterexample \
  generated/shrunk-fixtures/generated-no_cancelled_intents.jsonl \
  counter-no-cancelled-intents \
  --output fixtures/counter-no_cancelled_intents-001.jsonl

Promotion parses the source JSONL, applies the app’s redaction policy, and writes normalized observations. Use it after jacqos shrink-fixture when a failing generated scenario should become a permanent regression fixture.

jacqos fixture review

Runs verification for one fixture and writes a persona-specific review report under generated/fixture-reports/.

jacqos fixture review <FIXTURE> [--persona <PERSONA>]

Options:

Option	Description
--persona <PERSONA>	One of developer, risk-leader, auditor. Defaults to developer

jacqos fixture review fixtures/refund-threshold.jsonl --persona developer
jacqos fixture review fixtures/refund-threshold.jsonl --persona risk-leader
jacqos fixture review fixtures/refund-threshold.jsonl --persona auditor

The report points back to the verification bundle, evaluator digest, expected-world digest, golden status, and expected-diff counts. Developer reports focus on the next rule or mapper fix. Risk-leader reports focus on policy and contradiction-path coverage. Auditor reports focus on preserving the evidence needed to prove the reviewed behavior did not drift.

jacqos verify

Verifies the application against fixture expectations, invariants, mapper stability, determinism, and multi-agent composition boundaries when the app has more than one agent-owned namespace.

jacqos verify [--fixture <FIXTURE>] [--composition-report <REPORT>]

Options:

Option	Description
--fixture <FIXTURE>	Verify a specific fixture only (default: all fixtures)
--composition-report <REPORT>	Verify against an existing composition-analysis artifact during the same run

Example:

# Verify everything
jacqos verify

# Verify a specific fixture
jacqos verify --fixture happy-path

# Verify using a pinned composition-analysis artifact
jacqos verify --composition-report generated/verification/composition-analysis-sha256-7c419e9ed11d37434c5936a9aafeb9f68dd9a24b2ff159e6a93e2ecc3779343d.json

What it checks:

1. fixture_replay — fixture replay succeeds across the selected corpus
2. golden_fixtures — fixture output matches expected world state
3. invariants — invariant satisfaction across all fixture timelines
4. candidate_authority_lints — acceptance-gated evidence stays behind an explicit acceptance relation
5. provenance_bundle — provenance bundles export cleanly for every fixture
6. replay_determinism — same observations produce the same facts and intents
7. generated_scenarios — generated sequences find no invariant violations outside your checked-in fixtures
8. shadow_reference_evaluator — shadow evaluator conforms to the reference implementation
9. secret_redaction — secret material is absent from verification artifacts
10. composition — multi-agent composition analysis checks cross-namespace rule safety, layered dependency checks, and invariant fixture coverage

Check 10 is skipped automatically for apps with zero or one agent-owned namespace. When it runs and passes, jacqos verify writes a companion generated/verification/composition-analysis-<evaluator_digest>.json report and embeds the same artifact into the verification bundle. The report records namespace reduct partitions, cross-namespace dependencies, monotonicity summaries, and namespace-cycle severity. Use --composition-report when you want one verify run to confirm that a checked-in composition report still matches the current app inputs.

See Invariant Review and Golden Fixtures for the concepts behind verification.

jacqos studio

Launches JacqOS Studio for the drill inspector, timeline, ontology browser, and Activity lenses (replay, time travel, compare). Visual rule-graph and side-by-side worldview comparison views ship in V1.1.

jacqos studio [--lineage <LINEAGE>] [--snapshot]

Options:

Option	Description
--lineage <LINEAGE>	Open Studio against a specific lineage instead of the currently selected activation
--snapshot	Print the JSON snapshot that Studio would load instead of launching the UI

Example:

# Open Studio on the active lineage
jacqos studio

# Compare a child lineage against its parent
jacqos studio --lineage child-01

When you open a child lineage, Studio surfaces the parent-vs-child comparison through the Activity Compare lens chip. Side-by-side dual-pane rendering ships in V1.1; in V1 the lens chip pins the comparison evaluator’s identity but does not yet split the row stream. Fixture replays remain available as alternate comparison targets inside the UI.

jacqos lineage

Manages lineage branching operations.

jacqos lineage fork

Creates a child lineage from the committed head of the current lineage.

jacqos lineage fork

Output: JSON object containing the child lineage_id, parent_lineage_id, and fork_head_observation_id.

Use the returned lineage_id with jacqos replay --lineage ..., jacqos studio --lineage ..., jacqos export observations --lineage ..., and jacqos export facts --lineage ... to inspect the branch independently. Parent and child lineages never merge back.

jacqos stats

Displays statistics about the application and observation store.

jacqos stats

Output: JSON-formatted statistics report including observation counts, storage usage, audit-plane counts for attempt reports plus fact and intent history, monotonicity summaries, namespace-reduct partitions, and an agent_reduct_report that highlights shared multi-agent coordination surfaces, cross-namespace edges, and disjoint agent domains.

jacqos audit

Inspects the derived audit planes that record how facts, intents, and evaluation attempts changed across committed heads.

jacqos audit facts

Shows fact-plane additions and removals for one lineage between two committed heads.

jacqos audit facts --lineage <LINEAGE> --from <HEAD> --to <HEAD>

Options:

Option	Description
--lineage <LINEAGE>	Lineage to inspect
--from <HEAD>	Inclusive starting committed head
--to <HEAD>	Inclusive ending committed head

Example:

jacqos audit facts --lineage default --from 12 --to 18

Output: Aligned table with head, change, relation, and tuple columns.

jacqos audit intents

Shows when intents entered or exited the intent plane for one lineage between two committed heads.

jacqos audit intents --lineage <LINEAGE> --from <HEAD> --to <HEAD>

Options:

Option	Description
--lineage <LINEAGE>	Lineage to inspect
--from <HEAD>	Inclusive starting committed head
--to <HEAD>	Inclusive ending committed head

Example:

jacqos audit intents --lineage default --from 12 --to 18

Output: Aligned table with head, transition, relation, tuple, and request_id columns.

jacqos audit attempts

Lists evaluation attempts for one lineage and shows whether each attempt committed or was rejected.

jacqos audit attempts --lineage <LINEAGE>

Options:

Option	Description
--lineage <LINEAGE>	Lineage to inspect

Example:

jacqos audit attempts --lineage default

Output: Aligned table with head, outcome, and prior_committed_head columns.

jacqos gc

Garbage collection for the observation store.

jacqos gc [--dry-run]

Options:

Option	Description
--dry-run	Show what would be collected without deleting

Example:

# Preview what would be cleaned up
jacqos gc --dry-run

# Run garbage collection
jacqos gc

jacqos gc respects the retention.archive_after setting in jacqos.toml for archive-oriented cleanup and checkpoint inventory. In Phase A/B it does not silently collect observations, provider captures, attempt reports, run invocation records, lineage event rows, or idempotency rows.

jacqos reconcile

Manages effect reconciliation after crashes or ambiguous outcomes. See Crash Recovery for the full concept.

jacqos reconcile inspect

Inspects effects that need human resolution.

jacqos reconcile inspect [--session <SESSION>]

Options:

Option	Values	Description
--session	latest	Which session to inspect

Example:

jacqos reconcile inspect --session latest

Output: JSON array of reconciliation attempt summaries, including the original intent, capability, resource, timestamps, and what the shell knows about each attempt.

jacqos reconcile resolve

Resolves an effect reconciliation attempt after human investigation.

jacqos reconcile resolve <ATTEMPT_ID> <RESOLUTION>

Arguments:

Argument	Required	Values	Description
ATTEMPT_ID	Yes		The reconciliation attempt identifier
RESOLUTION	Yes	succeeded, failed, retry	Resolution decision

Example:

# The effect succeeded externally
jacqos reconcile resolve eff-0042 succeeded

# The effect failed — let the evaluator re-derive
jacqos reconcile resolve eff-0042 failed

# Safe to retry the effect
jacqos reconcile resolve eff-0042 retry

Every resolution appends a new observation with provenance. The evaluator re-runs and may derive new intents based on the outcome.

jacqos contradiction

Manages contradictions — conflicting assertions and retractions for the same fact.

jacqos contradiction list

Lists all active contradictions.

jacqos contradiction list

Output: JSON array of contradictions, including the conflicting fact, the assertion and retraction provenance, and timestamps.

jacqos contradiction preview

Previews the result of resolving a contradiction without committing.

jacqos contradiction preview <CONTRADICTION_ID> --decision <DECISION> [--note <NOTE>]

Arguments and options:

Parameter	Required	Values	Description
CONTRADICTION_ID	Yes		The contradiction identifier
--decision	Yes	accept-assertion, accept-retraction, defer	How to resolve
--note	No		Optional note for the resolution

Example:

jacqos contradiction preview ctr-007 --decision accept-assertion \
  --note "Confirmed with provider that slot is available"

jacqos contradiction resolve

Resolves a contradiction by committing a decision.

jacqos contradiction resolve <CONTRADICTION_ID> --decision <DECISION> [--note <NOTE>]

Takes the same arguments as preview. The resolution is recorded as an observation with full provenance.

jacqos export

Exports data and artifacts from the application.

jacqos export observations

Exports the observation log in JSONL format.

jacqos export observations [--lineage <LINEAGE>]

Options:

Option	Description
--lineage	Filter by lineage identifier

jacqos export facts

Exports derived facts.

jacqos export facts [--lineage <LINEAGE>]

Options:

Option	Description
--lineage	Filter by lineage identifier

Output: Path to the exported facts artifact.

jacqos export evaluation-package

Exports a frozen evaluation package — the portable contract boundary containing the ontology IR, mapper semantics, and helper digests.

jacqos export evaluation-package

Output: Path to the evaluation package artifact. See Evaluation Package for the format.

jacqos export verification-bundle

Exports a redacted verification bundle containing proof artifacts from jacqos verify.

jacqos export verification-bundle [--fixture <FIXTURE>]

Options:

Option	Description
--fixture <FIXTURE>	Bundle a single fixture instead of the full corpus (default: all fixtures)

jacqos export migration-package

Exports the V1 local-to-cloud migration package for one lineage.

jacqos export migration-package [--lineage <LINEAGE>]

Options:

Option	Description
--lineage <LINEAGE>	Export a specific lineage (default: default)

Output: Path to the migration-package artifact under generated/jacqos-v1/.

The package references the evaluation package, redacted observations, verification bundle, app files, BlobRefs, and migration manifests. Cloud and enterprise importers must reject missing artifacts, digest mismatches, unsupported versions, and semantic identity drift.

jacqos export composition-analysis

Exports the portable composition-analysis artifact for the current app and fixture corpus.

jacqos export composition-analysis

Output: Path to the composition-analysis artifact under generated/verification/, with a filename of the form composition-analysis-<evaluator_digest>.json.

This export is static: it reads the ontology plus fixture expectations and does not depend on replayed store state. Use it when you want to pin namespace boundaries, monotonicity summaries, or invariant-fixture coverage even for an app where jacqos verify skipped the multi-agent composition gate.

Example:

jacqos export composition-analysis

# Validate the exported report later
jacqos composition verify-report generated/verification/composition-analysis-sha256-7c419e9ed11d37434c5936a9aafeb9f68dd9a24b2ff159e6a93e2ecc3779343d.json

jacqos export graph-bundle

Stability: draft local

Authority: This export remains local to tools/jacqos-cli/protocols/README.md until it is explicitly promoted. Current artifact version: jacqos_graph_bundle_v1.

Exports a graph bundle with provenance information for Studio and local tooling.

jacqos export graph-bundle [--fixture <FIXTURE>]

Options:

Option	Description
--fixture <FIXTURE>	Restrict the bundle to a single fixture (default: all fixtures)

jacqos export benchmark-report

Stability: draft local

Authority: This export remains local to tools/jacqos-cli/protocols/README.md until it is explicitly promoted. Current artifact version: jacqos_benchmark_report_v1.

Exports a benchmark report with replay and refresh metrics for local verification and release smoke checks.

jacqos export benchmark-report [--fixture <FIXTURE>]

Options:

Option	Description
--fixture <FIXTURE>	Restrict the benchmark to a single fixture (default: all fixtures)

All export subcommands that accept --fixture default to including all fixtures when omitted.

jacqos composition

Inspects or validates the portable composition-analysis report.

jacqos composition check

Recomputes composition analysis for the current app and optionally compares it to a report on disk.

jacqos composition check [--report <REPORT>]

Options:

Option	Description
--report <REPORT>	Validate and compare a specific composition-analysis report instead of the default checked-in report

If --report is omitted and generated/verification/<app_id>.composition-analysis.json already exists, the command verifies that file and tells you whether it matches the current app inputs.

jacqos composition verify-report

Validates one composition-analysis artifact against the portable schema and its embedded digest contract.

jacqos composition verify-report <REPORT>

Use this when you want to check a generated report in CI or inspect a report copied out of a verification bundle without re-running the rest of the app.

jacqos self-update

Checks for and installs the latest version of the jacqos binary.

jacqos self-update [--check]

Options:

Option	Description
--check	Only check for updates and report the latest available version without installing

Example:

# See whether a newer release is available
jacqos self-update --check

# Install the latest release in place
jacqos self-update

Global behavior

• Commands that accept --lineage default to the default lineage.
• observe --json, activation ... --json, and run --json print stable JSON receipts for programmatic clients.
• stats, gc, reconcile, and contradiction print JSON for machine consumption.
• audit prints aligned tables for human inspection of fact, intent, and attempt history.
• export observations streams JSONL (one JSON object per line).
• Artifact-style export commands print the relative path to the written artifact.
• The CLI expects to run in a directory containing jacqos.toml (or a subdirectory of one).
• Exit codes: 0 for success, 1 for failure, 2 for verification failures.

Next Steps

• jacqos.toml Reference — configuration format
• Evaluation Package — the portable contract boundary
• Getting Started — install and try the CLI
• Crash Recovery — understanding reconciliation