Textbook 08 CAVRA CLI Command Reference

CAVRA CLI Command Reference

The cavra CLI is the main command surface for local users, automation, CI/CD, release workflows, and evidence operations.

For the complete generated command list, see CLI. This chapter groups the commands by job-to-be-done.

Core Commands

cavra version
cavra evaluate <action> <resource>

Use cavra evaluate to ask CAVRA whether an action should proceed.

Practical examples:

cavra evaluate read_file .env --json
cavra evaluate write_file iam/admin-role.tf --json
cavra evaluate execute_command "terraform apply -auto-approve" --json
cavra evaluate git_operation origin/main --json
cavra evaluate mcp_tool_call unknown-filesystem --json

Expected outcomes under the starter baseline:

Command	Why you run it	Typical decision
read_file .env	Confirm secrets are protected.	Block
write_file iam/admin-role.tf	Test identity/IAM change control.	Requires approval
execute_command "terraform plan"	Confirm safe planning can proceed.	Allow
execute_command "terraform apply -auto-approve"	Confirm destructive unattended execution is stopped.	Block
git_operation origin/main	Confirm branch protection is respected.	Block
mcp_tool_call unknown-filesystem	Confirm untrusted tool calls are blocked.	Block

Agent Commands

cavra agent start
cavra agent exec
cavra agent attest

Use these commands to run governed agent sessions and produce attestations.

Policy Commands

cavra policy list
cavra policy validate
cavra policy test
cavra policy explain
cavra policy sign
cavra policy verify

Use policy commands to manage policy packs and confirm that rules behave as expected.

Policy authoring loop:

cavra policy init --destination .cavra/policy.yaml
cavra policy validate .cavra/policy.yaml
cavra policy test --policy-pack cavra-ai-agent-baseline
cavra policy explain execute_command "terraform apply -auto-approve"
cavra policy keygen
cavra policy sign .cavra/policy.yaml --signer platform-security --private-key .cavra/policy-signing/local-policy-signing-key.private.pem --key-id local-policy-signing-key
cavra policy verify .cavra/policy.yaml --public-key .cavra/policy-signing/local-policy-signing-key.public.pem

Use validate for schema correctness, test for expected behavior, explain for human-readable reasoning, and sign/verify when the policy will be used in stricter governance workflows.

Approval Commands

cavra approval create
cavra approval list
cavra approval approve
cavra approval deny
cavra approval expire
cavra approval break-glass
cavra approval route
cavra approval migrate
cavra approval export-notifications
cavra approval provider-requests
cavra approval deliver

Approval commands turn high-risk decisions into auditable human or external-provider workflows.

Approval example:

cavra evaluate write_file iam/admin-role.tf --json > /tmp/cavra-decision.json
cavra approval create /tmp/cavra-decision.json --requested-by developer
cavra approval list --state pending
cavra approval approve apr_123 --actor platform-security --reason "Scoped IAM change reviewed"

Use approval routing when the action may be legitimate but should not proceed without a named human, reason, and review record.

Evidence Commands

cavra evidence generate-keypair
cavra evidence trust-root .cavra/keys/evidence-ed25519-public.pem --key-id local-evidence-key
cavra evidence trust-bundle .cavra/keys/evidence-trust-root.json
cavra evidence trust-distribution
cavra evidence bundle
cavra evidence verify
cavra evidence verify-attestation
cavra evidence siem-event
cavra evidence export-siem
cavra evidence retention-policy
cavra evidence storage-plan
cavra evidence migrate
cavra evidence index
cavra evidence search

Evidence commands produce and validate the proof that CAVRA decisions were made and enforced.

Evidence example:

cavra evidence generate-keypair
cavra evidence trust-root .cavra/keys/evidence-ed25519-public.pem --key-id local-evidence-key
cavra evidence bundle --output .cavra/evidence/latest --private-key .cavra/keys/evidence-ed25519-private.pem --key-id local-evidence-key
cavra evidence verify .cavra/evidence/latest --trust-root .cavra/keys/evidence-trust-root.json
cavra evidence siem-event .cavra/evidence/latest

Use evidence commands whenever decisions must feed CI/CD gates, audit, SIEM export, AISPM, or report delivery.

Registry Commands

cavra registry agent-register
cavra registry agent-list
cavra registry profiles
cavra registry mcp-register
cavra registry mcp-list
cavra registry mcp-check
cavra registry mcp-classifications
cavra registry migrate

Registry commands manage governed agent identities and MCP trust records.

MCP trust example:

cavra registry mcp-register github-mcp --trust-tier approved --approval-state approved --capability repository --tool create_pull_request
cavra registry mcp-check github-mcp create_pull_request --capability repository

Use the registry when a tool call is more important than a file operation. CAVRA should know which MCP servers are trusted, what capabilities they expose, and whether a tool is allowed for the current action.

Operations Commands

cavra ops stores
cavra ops backup
cavra ops restore
cavra ops retention-plan

Operations commands support persistence, backup, restore, and retention planning.

Runtime And Release Commands

Runtime and release commands cover Go backend operations, rollback rehearsals, endpoint rollout, package verification, channel promotion, endpoint reconciliation, remediation, SLA reporting, and connector delivery. These commands are advanced and should be used with the detailed CLI, Go Backend Deployment Readiness, and Release Security Advisories pages.

Demo And Setup Commands

cavra init claude-code
cavra demo before-the-agent-acts

Use these commands to initialize Claude Code integration and run the flagship demonstration.

The fastest CLI learning path is:

cavra demo before-the-agent-acts
cavra policy explain execute_command "terraform apply -auto-approve"
cavra evidence bundle --output .cavra/evidence/latest --private-key .cavra/keys/evidence-ed25519-private.pem --key-id local-evidence-key
cavra evidence verify .cavra/evidence/latest

Check Your Understanding

1. Which command explains a policy decision before you change the policy?
2. Which command family proves evidence after an action is evaluated?
3. Why should CLI examples be run against the same policy pack used in CI/CD?

What's Next

Read CAVRA GUI And Sandbox Guide to see the same runtime story in the visual product surface.