CLI Reference

The Asqav CLI ships as an extra of the Python SDK. Install with pip install "asqav[cli]" and you have every command below. Most commands wrap a Python function of the same name. Use the SDK directly when you want programmatic control. All commands that talk to the API read ASQAV_API_KEY from the environment.

Set ASQAV_API_KEY in the environment, then run any command below.

Quickstart

Sixty-second guided walk-through. Detects whether ASQAV_API_KEY is set, prints the MCP config block for .mcp.json, a default Policy example, and the four next steps for a new install (create an agent, sign actions, verify anywhere, run asqav doctor).

$ asqav quickstart

Doctor

Validate your governance setup. Runs three checks in order: (1) ASQAV_API_KEY is set, (2) the API is reachable via health_check(), (3) reports the installed SDK version. Exits non-zero on any failure, so it works as the first step in a CI workflow. The API-reachable check is skipped (not failed) when the key is missing.

$ asqav doctor

Verify

Verify a signature by its ID. Public, no auth needed - calls asqav.verify_signature(signature_id) against the public verification surface. With --output json the full VerificationResponse is returned, including the IETF profile sub-axes (chain_valid, anchor_status_ots, anchor_status_rfc3161, signed_at_skew_seconds, missing_fields) when the cloud emitted them. Exits 1 if the signature is not found.

$ asqav verify SIGNATURE_ID [--output text|json]

Arguments

• SIGNATURE_ID - Signature ID to verify.

Options

• --output, -o text|json - Output format (default: text).

$ asqav verify SIGNATURE_ID [--output text|json]

Sign

Issue a Compliance Receipt via the cloud /agents/{id}/sign route. Mirrors Agent.sign() end-to-end so every flag here maps 1:1 to a kwarg on the SDK call. Pass --action-json - to read the canonical Action JSON from stdin. The SDK derives action_ref from the JCS bytes when --action-ref is empty. When --policy-decision is deny or rate_limit, --reason is required.

$ asqav sign --agent-id AGENT --action-type TYPE [options]

Options

• --agent-id - Agent that signs the receipt (required).
• --action-type - Action type, e.g. payment.wire_transfer (required).
• --action-id - Stable client-side action id. The cloud allocates one when empty.
• --compliance-mode / --no-compliance-mode - Emit the receipt under the IETF Compliance Receipts profile (default: off).
• --action-ref - sha256:<hex> over the canonical Action object. Auto-computed when omitted with --action-json.
• --action-json - Path to a JSON file, or - for stdin.
• --sandbox-state - enabled|disabled|unavailable.
• --iteration-id - Logical task iteration id (distinct from session_id).
• --risk-class - low|medium|high|unknown.
• --incident-class - DORA RTS JC 2024-33 Annex II field 3.23: cybersecurity_related|process_failure|system_failure|external_event|payment_related|other.
• --issuer-id - Legal entity issuing the receipt. Overrides server resolution.
• --receipt-type - protectmcp:decision|protectmcp:restraint|protectmcp:lifecycle (default: protectmcp:decision).
• --reason - Required when --policy-decision is deny or rate_limit.
• --policy-decision - permit|deny|rate_limit (default: permit).
• --algorithm - ml-dsa-65|ed25519|es256 (default: ml-dsa-65). Algorithm is bound server-side. A mismatch with the agent's algorithm prints a warning.
• --session-id - Bind the record to an existing session.
• --valid-seconds - Validity window in seconds (0 = no expiry).
• --policy-artefact - Path to a JSON file, or - for stdin. Retained server-side. The receipt's policy_digest is its content hash.
• --output, -o text|json - Output format (default: text).

$ asqav sign \

Sync

Flush the local offline queue to the API. Prints one line per item with success ([ok]) or failure ([fail]) and a summary count at the end. Failed items remain queued for the next call.

$ asqav sync

Demo

Run the local governance demo dashboard. Opens http://localhost:3030 with four pre-loaded scenarios (rm -rf, fintech wire transfer, k8s scale-to-zero, clinical lab order). No signup, no Docker, no API key required.

$ asqav demo [--port PORT] [--no-browser]

Options

• --port - Port for the local dashboard (default: 3030).
• --no-browser - Do not auto-open a browser.

$ asqav demo [--port PORT] [--no-browser]

Agents

Manage agents for your organization. The group exposes list, create, and revoke. All three read ASQAV_API_KEY from the environment.

Agents List

List all agents for your organization. Prints one row per agent: name (agent_id) [algorithm].

$ asqav agents list

Agents Create

Create a new agent. Wraps asqav.Agent.create(name). The cloud mints the keypair. The response includes the agent ID, algorithm, and key ID.

Arguments

• NAME - Name for the new agent.

$ asqav agents create my-agent

Agents Revoke

Revoke an agent's credentials. Irreversible. The reason is recorded in the audit trail.

$ asqav agents revoke AGENT_ID [--reason REASON]

Arguments

• AGENT_ID - Agent ID to revoke.

Options

• --reason - Reason recorded in the audit trail (default: manual).

$ asqav agents revoke agt_x7y8z9 --reason "key rotation"

Sessions

List sessions for the current org and end them when work is done. Wraps the /sessions surface.

Sessions List

List sessions. Prints one row per session with session ID, agent ID, status, and start time.

$ asqav sessions list [--limit N] [--status STATUS] [--agent AGENT_ID]

Options

• --limit - Max sessions to return (default: 50).
• --status - Filter by session status.
• --agent - Filter by agent_id.

$ asqav sessions list --limit 20 --status active

Sessions End

End a session by setting its status. PATCHes /sessions/{session_id}.

$ asqav sessions end SESSION_ID [--status STATUS]

Arguments

• SESSION_ID - Session to end.

Options

• --status - Final status (default: completed).

$ asqav sessions end sess_abc123 --status completed

Queue

Inspect and clear the local offline queue used when the API is unreachable. Pair with asqav sync to flush.

Queue List

List pending items in the local queue. Prints one row per item: id, action type, agent, queued-at.

$ asqav queue list

Queue Count

Show number of pending items in the local queue.

$ asqav queue count

Queue Clear

Clear all pending items from the local queue. Prompts for confirmation unless --yes is passed.

$ asqav queue clear [--yes]

Options

• --yes, -y - Skip confirmation.

$ asqav queue clear --yes

Audit Pack

Audit Pack export and policy_digest resolution under the IETF Compliance Receipts profile.

Audit-Pack Export

Export a signed Audit Pack bundle of receipts in [start, end). Calls POST /audit-pack/export. The bundle is signed with the org's most-recent active agent key over the JCS-canonical bundle bytes, so a verifier can rederive the digest and check the signature offline.

$ asqav audit-pack export --start ISO --end ISO --output-file FILE [options]

Options

• --start - Window start, ISO 8601 (UTC) (required).
• --end - Window end, ISO 8601 (UTC). Half-open (required).
• --organization-id - Defaults to the caller's org. Cross-org export requires admin scopes.
• --only-compliance / --no-only-compliance - When true, only IETF Compliance Receipts are exported (default: on).
• --output-file - Path to write the signed bundle JSON (required).

$ asqav audit-pack export \

Audit-Pack Policy

Resolve a policy_digest to the retained policy artefact JSON. Calls GET /audit-pack/policy/{digest}. The receipt's policy_digest is sha256:<hex> over the canonical artefact JSON. This command fetches the artefact so a verifier can rederive the digest offline. Accepts both sha256:<hex> and bare 64-hex strings.

$ asqav audit-pack policy DIGEST [--output json|text]

Arguments

• DIGEST - sha256:<hex> digest, or 64-hex (the prefix is added).

Options

• --output, -o json|text - Output format (default: json).

$ asqav audit-pack policy DIGEST [--output json|text]

See EU AI Act Audit Pack for the bundle format.

Payloads

Erase persisted payloads for GDPR / UK-GDPR right-to-erasure flows.

Payloads Erase

Erase the persisted JSON payload for a signature record. Calls DELETE /signatures/payloads/{signature_id}. The cryptographic message bytes and chain hash stay untouched so the receipt remains verifiable. The human-readable JSON payload is replaced with a tombstone marker. Idempotent: replaying on an already-erased record returns 204. Prompts for confirmation unless --yes is passed.

$ asqav payloads erase SIGNATURE_ID [--yes]

Arguments

• SIGNATURE_ID - Signature whose payload bytes are erased.

Options

• --yes, -y - Skip the confirmation prompt.

$ asqav payloads erase SIGNATURE_ID [--yes]

Org

Organization-level settings.

Org Set-Compliance-Strict

Toggle per-org compliance_mode_strict. When enabled, the cloud rejects any sign request that is not flagged compliance_mode=true with HTTP 412 so non-instrumented call paths cannot slip past the receipts trail. Calls PATCH /orgs/{org_id} with {"compliance_mode_strict": <bool>}. Pass exactly one of --enable or --disable.

$ asqav org set-compliance-strict ORG_ID (--enable | --disable)

Arguments

• ORG_ID - Organization ID to update.

Options

• --enable - Turn strict mode on.
• --disable - Turn strict mode off.

$ asqav org set-compliance-strict ORG_ID (--enable | --disable)

Keys

Local keypair management for algorithm agility, offline, and air-gapped flows.

Keys Generate

Generate a local keypair. Ed25519 and ES256 emit PKCS#8 PEM. ML-DSA-65 keygen is server-side only. The command rejects --algorithm ml-dsa-65 with an unsupported_algorithm error. Use asqav agents create to mint an ML-DSA key via the cloud KMS instead. When --out is set, the private key is written with mode 0600. The public key always prints to stdout.

$ asqav keys generate [--algorithm ed25519|es256] [--out PATH]

Options

• --algorithm - ed25519|es256 (default: ed25519).
• --out - Path to write the private key bytes.

$ asqav keys generate [--algorithm ed25519|es256] [--out PATH]

See Key Management for the cloud KMS path.

Migrate

Operator-only DB migration runner. Requires both ASQAV_API_KEY and ASQAV_MAINTENANCE_KEY in the environment.

Migrate Run

Trigger a maintenance migration. POSTs /maintenance/run-migration-{migration} with the X-Maintenance-Key header. Refuses to run when ASQAV_MAINTENANCE_KEY is missing.

Arguments

• MIGRATION - One of v3-20, v3-21, v3-22.

$ asqav migrate run MIGRATION

Replay

Replay an agent's audit trail. Wraps asqav.replay() for the online path and asqav.replay_from_bundle() for the offline path. The online form requires both arguments. The offline form reads a compliance bundle JSON via --bundle. Exits non-zero if the chain integrity check fails. Use --output FILE to persist the timeline as JSON. This implies --json.

$ asqav replay [AGENT_ID] [SESSION_ID] [--bundle FILE] [--json] [--output FILE]

Arguments

• AGENT_ID - Agent ID. Omit when using --bundle.
• SESSION_ID - Session ID to replay. Omit when using --bundle.

Options

• --bundle, -b - Replay from a compliance bundle JSON file (offline).
• --json - Print the timeline as JSON instead of a human-readable summary.
• --output, -o - Write the timeline to FILE (JSON). Implies --json.

$ asqav replay [AGENT_ID] [SESSION_ID] [--bundle FILE] [--json] [--output FILE]

See Replay API for the underlying endpoint.

Replay Verify

Re-derive a session's IETF chain (sha256(canonical_json(signed_envelope))) and verify every step. Wraps asqav.replay() and runs timeline.verify_chain(). With --strict the command fails when any step lacks the cloud-emitted signed_envelope, so synthetic-shape fallback steps cannot prove byte-level integrity and cannot pass the gate.

$ asqav replay-verify AGENT_ID SESSION_ID [--strict] [--output text|json]

Arguments

• AGENT_ID - Agent that owns the chain.
• SESSION_ID - Session whose chain to re-derive.

Options

• --strict - Require every step to carry a cloud signed_envelope.
• --output, -o text|json - Output format (default: text).

$ asqav replay-verify AGENT_ID SESSION_ID [--strict] [--output text|json]

Preflight

Run a pre-flight check (revocation + suspension + policy) for an action. Wraps Agent.get(agent_id).preflight(action_type). Exits non-zero when the action is blocked, so it works as a gate in shell pipelines. Prints the verdict (CLEARED / BLOCKED), the explanation, and a bulleted list of reasons.

$ asqav preflight AGENT_ID ACTION_TYPE [--json]

Arguments

• AGENT_ID - Agent ID to check.
• ACTION_TYPE - Action to evaluate (e.g. data:read).

Options

• --json - Print result as JSON (default: text).

$ asqav preflight AGENT_ID ACTION_TYPE [--json]

Approve

Approve a pending signing-action session. Wraps asqav.approve_action(). Output shows progress as signatures_collected/approvals_required and the session status (APPROVED when the threshold is reached, otherwise PENDING).

$ asqav approve SESSION_ID ENTITY_ID [--json]

Arguments

• SESSION_ID - Signing session to approve.
• ENTITY_ID - Entity providing approval.

Options

• --json - Print result as JSON.

$ asqav approve SESSION_ID ENTITY_ID [--json]

See Approvals for the workflow this fits into.

Policies

Manage organization policies. The action enforced for a matching pattern is one of log, block, or block_and_alert.

Policies List

List all org policies. Prints one row per policy with ID, name, action pattern, action, and active/inactive flag.

$ asqav policies list

Policies Create

Create a new policy. Defaults to --pattern "*" and --action block.

$ asqav policies create --name NAME [--pattern PATTERN] [--action ACTION]

Options

• --name - Policy name (required).
• --pattern - Action pattern, e.g. data:* (default: *).
• --action - One of log, block, block_and_alert (default: block).

$ asqav policies create --name "block-writes" --pattern "data:write" --action block

Policies Delete

Delete a policy by ID.

Arguments

• POLICY_ID - Policy ID to delete.

$ asqav policies delete pol_abc123

See Policies for the policy model.

Webhooks

Manage outbound webhook subscriptions. Events are passed as a comma-separated list and stored as an array on the server.

Webhooks List

List configured webhooks. Prints one row per webhook: ID, URL, and the subscribed events.

$ asqav webhooks list

Webhooks Create

Create a webhook subscription. URL should be HTTPS.

$ asqav webhooks create --url URL [--events EVENTS]

Options

• --url - Webhook target URL, HTTPS (required).
• --events - Comma-separated event names (default: signature.created).

$ asqav webhooks create --url https://example.com/hook --events signature.created,policy.blocked

Webhooks Delete

Delete a webhook by ID.

Arguments

• WEBHOOK_ID - Webhook ID.

$ asqav webhooks delete whk_abc123

See Webhooks for event payloads.

Budget

Check or record agent spend. Wraps asqav.BudgetTracker.

Budget Check

Stateless arithmetic check: would --estimated-cost push --current-spend past --limit? Returns ALLOWED / DENIED plus the remaining headroom, and exits non-zero on DENIED. For server-side enforcement use budget record.

$ asqav budget check --agent-id ID --limit X --estimated-cost X [options]

Options

• --agent-id - Agent ID (required).
• --limit - Budget ceiling (required).
• --estimated-cost - Cost of the pending action (required).
• --current-spend - Cumulative spend so far (default: 0.0).
• --currency - Currency code (default: USD).
• --json - Print result as JSON.

$ asqav budget check \

Budget Record

Sign a tamper-evident spend record on the server. The signed payload includes the cost, currency, cumulative spend after the record, and the configured limit.

$ asqav budget record --agent-id ID --action TYPE --actual-cost X --limit X [options]

Options

• --agent-id - Agent ID (required).
• --action - Action being recorded (required).
• --actual-cost - Realized cost (required).
• --limit - Budget ceiling for the signed payload (required).
• --current-spend - Cumulative spend prior to this record (default: 0.0).
• --currency - Currency code (default: USD).

$ asqav budget record \

Compliance

Compliance bundle export. Wraps asqav.compliance.export_bundle.

Compliance Frameworks

List the compliance frameworks the bundle exporter recognizes. Prints one row per framework: key<TAB>name.

$ asqav compliance frameworks

Compliance Export

Pull a session's signatures and export a Merkle-rooted compliance bundle. Wraps get_session_signatures() + export_bundle(). Use asqav compliance frameworks to list valid keys.

$ asqav compliance export --session SESSION --output FILE [--framework KEY]

Options

• --session - Session ID to bundle signatures from (required).
• --framework - Compliance framework key (default: eu_ai_act).
• --output, -o - File to write the bundle JSON to (required).

$ asqav compliance export \

Related

• GitHub Actions - drop-in CI workflow that runs asqav doctor and exports a compliance bundle.
• pytest plugin - capture every signed action during tests and emit a bundle artifact.
• API Reference - direct HTTP API for everything the CLI does.