CLI - Pactmark

Compatibility: Pactmark 0.1.x. The pactmark binary is owned by @pactmark/cli and operates over injected host adapters. Commands validate unknown input and authority before mutation.

Usage

pactmark <command> [options]

Commands:
  dev
  compile
  run <agent> --input <file-or-json>
  inspect <runId>
  events <runId> [--after <sequence>]
  replay <runId>
  doctor [--profile local|preview|production] [--production]
  test [scenario]
  eval [suite]
  evidence export <runId> [--format json|md]
  evidence verify <path>
  audit verify <runId>
  migrate status|up
  policy explain <fixture>
  effects reconcile <runId> <effectId> --resolution <file-or-json>
  effects compensate <runId> <effectId> --request <file-or-json>

Global options: --json --debug --help --version

Use --json for automation and branch on stable KAF_* codes. Human text, ordering outside the documented contract, and stack traces are not stable APIs.

Development

Local development loop

Runs the project’s development entrypoint.

Build the agent manifest

Reads AGENT.md and optional skills/* inputs, then atomically writes .pactmark/generated/agent-manifest.json.

Execute a run

npx pactmark run support-refund-agent --input ./fixtures/refund.json --json

Inspection

Current projection

Status, sequence, waiting ids, artifact and verification ids, terminal error code.

Event stream

npx pactmark events run_01J8… --after 42 --json

Verify without executing

Verifies a terminal run from stored events and artifacts without executing any tool or model. If a run cannot be replayed, its history is not intact.

Verify audit bindings

Checks that authority and decision records resolve consistently.

Diagnostics

npx pactmark doctor --profile production --json

Production doctor fails when required durability, sandbox, credential, policy or registration evidence is absent. On a fresh memory-backed project it should fail — read the gaps as a checklist.

npx pactmark policy explain ./fixtures/refund-r4.json --json

Explains a policy decision against a fixture. Useful in review, and useful for proving a denial is intentional.

Evidence

npx pactmark evidence export run_01J8… --format json > evidence.json

npx pactmark evidence export run_01J8… --format md > evidence.md

npx pactmark evidence verify ./evidence.json --json

evidence verify re-checks internal references; a missing or incompatible record surfaces as KAF_EVIDENCE_INVALID_REFERENCE.

Migrations

npx pactmark migrate status --json
npx pactmark migrate up --json

Ordered and forward-applied. Test a representative upgrade, a projection rebuild, a rollback plan, a backup restore and old-run inspection before a production rollout.

Effects

npx pactmark effects reconcile <runId> <effectId> \
  --resolution '{"kind":"recovered_acknowledgement","providerRef":"re_1Nc…"}' --json

npx pactmark effects compensate <runId> <effectId> \
  --request '{"reason":"incident_resolved","approvedBy":"role:sre_lead"}' --json

effects reconcile records what you established, not what you assume. A resolution of abandon_uncertain explicitly records that the effect may have occurred — and anything depending on it raises KAF_EFFECT_ABANDONED_UNCERTAIN.

effects compensate starts a separate authorised compensation run. It is not an undo.

Tests and evals

npx pactmark test --json
npx pactmark eval --json

Scripting it

#!/usr/bin/env bash
set -euo pipefail

result=$(npx pactmark inspect "$RUN_ID" --json)
status=$(jq -r '.status' <<<"$result")

case "$status" in
  completed) npx pactmark evidence export "$RUN_ID" --format json > "evidence-$RUN_ID.json" ;;
  failed)    jq -r '.terminalErrorCode' <<<"$result" | xargs -I{} ./notify.sh {} ;;
  *)         echo "still running: $status" ;;
esac

Branch on .status and .terminalErrorCode, never on printed prose.

Error reference

The codes your scripts should branch on.

HTTP API

The same surfaces over the wire.

​Usage

​Development

​Inspection

​Diagnostics

​Evidence

​Migrations

​Effects

​Tests and evals

​Scripting it

Error reference

HTTP API

Usage

Development

Inspection

Diagnostics

Evidence

Migrations

Effects

Tests and evals

Scripting it