acpctl.md

ACPCTL Reference

Generated from the typed command registry. Do not edit manually.

acpctl is the typed implementation engine for supported host-first workflows. make remains the primary human operator UX.

Top-Level Commands

ci

CI and local gate helpers.

Subcommand	Summary
should-run-runtime	Decide whether runtime checks should run
wait	Wait for services to become healthy

Examples:

./scripts/acpctl.sh ci should-run-runtime --quiet
./scripts/acpctl.sh ci wait --timeout 120

env

Strict .env access helpers.

Subcommand	Summary
get	Read a single env key without shell execution

Examples:

./scripts/acpctl.sh env get LITELLM_MASTER_KEY
./scripts/acpctl.sh env get --file demo/.env DATABASE_URL

chargeback

Typed chargeback rendering helpers.

Subcommand	Summary
report	Generate canonical chargeback report artifacts
render	Render canonical chargeback JSON or CSV
payload	Render canonical chargeback webhook payload JSON

Examples:

./scripts/acpctl.sh chargeback report
./scripts/acpctl.sh chargeback report --organization falcon-insurance --workspace claims-adjuster
./scripts/acpctl.sh chargeback render --format json
./scripts/acpctl.sh chargeback render --format csv
./scripts/acpctl.sh chargeback payload --target generic

tenant

Inspect and validate the design-only multi-tenant package.

Subcommand	Summary
inspect	Print a concise summary of the tracked tenant design package
validate	Validate the tracked tenant design package and truth markers

Examples:

./scripts/acpctl.sh tenant inspect
./scripts/acpctl.sh tenant inspect --format json
./scripts/acpctl.sh tenant validate

evidence

Vendor evidence ingest workflows.

Subcommand	Summary
ingest	Normalize supported vendor evidence into ACP schema artifacts

Examples:

./scripts/acpctl.sh evidence ingest --format compliance-api --file examples/vendor-evidence/compliance_export.sample.json
cat export.json | ./scripts/acpctl.sh evidence ingest --format compliance-api

policy

ACP-native custom policy evaluation workflows.

Subcommand	Summary
eval	Evaluate local request/response records against custom ACP guardrails

Examples:

./scripts/acpctl.sh policy eval --file examples/policy-engine/request_response_eval.sample.json
cat request_response_eval.sample.json | ./scripts/acpctl.sh policy eval

ops

Operator reporting workflows.

Subcommand	Summary
report	Render a canonical operator status report

status

Aggregated system health overview.

Examples:

./scripts/acpctl.sh status
./scripts/acpctl.sh status --json
./scripts/acpctl.sh status --wide
./scripts/acpctl.sh status --watch --interval 5

health

Run service health checks.

Examples:

./scripts/acpctl.sh health
./scripts/acpctl.sh health --verbose

doctor

Environment preflight diagnostics.

Examples:

./scripts/acpctl.sh doctor
./scripts/acpctl.sh doctor --json
./scripts/acpctl.sh doctor --fix --skip-check db_connectable
./scripts/acpctl.sh doctor --notify
./scripts/acpctl.sh doctor --wide

benchmark

Lightweight local performance baseline.

Subcommand	Summary
baseline	Run the local gateway performance baseline

Examples:

./scripts/acpctl.sh benchmark baseline
./scripts/acpctl.sh benchmark baseline --profile interactive
./scripts/acpctl.sh benchmark baseline --requests 40 --concurrency 4
./scripts/acpctl.sh benchmark baseline --json

smoke

Run truthful runtime smoke checks.

Examples:

./scripts/acpctl.sh smoke
./scripts/acpctl.sh smoke --verbose

completion

Generate shell completion scripts.

Subcommand	Summary
bash	Generate Bash completion script
zsh	Generate Zsh completion script
fish	Generate Fish completion script

onboard

Launch the guided onboarding wizard.

Examples:

./scripts/acpctl.sh onboard
./scripts/acpctl.sh onboard codex
make onboard
make onboard-codex

deploy

Typed evidence and artifact workflows.

Subcommand	Summary
release-bundle	Build deployment release bundle
readiness-evidence	Generate and verify dated readiness evidence
pilot-closeout-bundle	Assemble and verify a pilot closeout evidence bundle
assessor-packet	Assemble and verify an ACP-native assessor handoff packet
artifact-retention	Enforce document artifact retention policy

Examples:

./scripts/acpctl.sh deploy readiness-evidence run
./scripts/acpctl.sh deploy release-bundle build
./scripts/acpctl.sh deploy pilot-closeout-bundle build
./scripts/acpctl.sh deploy assessor-packet build

validate

Configuration and policy validation operations.

Subcommand	Summary
lint	Run static validation/lint gate
config	Validate deployment configuration (use --production for host contract checks)
detections	Validate detection rule output
siem-queries	Validate SIEM query sync
policy-rules	Validate the tracked ACP custom policy rule contract
tenant	Validate the tracked tenant design package and truth markers
public-hygiene	Fail when local-only files are tracked by git
license	Validate license policy structure and restricted references
supply-chain	Run supply-chain policy and digest validation
secrets-audit	Run deterministic tracked-file secrets audit
compose-healthchecks	Validate Docker Compose healthchecks
headers	Validate Go source file header policy
env-access	Fail on direct environment access outside internal/config
security	Run Make-composed security gate (hygiene, secrets, license, supply chain)

Examples:

./scripts/acpctl.sh validate config
./scripts/acpctl.sh validate config --production --secrets-env-file /etc/ai-control-plane/secrets.env
./scripts/acpctl.sh validate lint
./scripts/acpctl.sh validate detections
./scripts/acpctl.sh validate policy-rules
./scripts/acpctl.sh validate tenant

db

Database backup, restore, and inspection operations.

Subcommand	Summary
status	Show database status and statistics
backup	Create database backup
backup-retention	Enforce backup retention policy
restore	Restore embedded database from backup
off-host-drill	Validate a staged off-host backup copy and emit staged-local or separate-host recovery evidence
shell	Open database shell
dr-drill	Create a fresh backup and verify restore into a scratch database

Examples:

./scripts/acpctl.sh db status
./scripts/acpctl.sh db backup
./scripts/acpctl.sh db backup-retention --check
./scripts/acpctl.sh db off-host-drill --manifest demo/logs/recovery-inputs/off_host_recovery.yaml
./scripts/acpctl.sh db off-host-drill --manifest demo/config/off_host_recovery.separate_host.yaml
./scripts/acpctl.sh db dr-drill

key

Virtual key lifecycle operations.

Subcommand	Summary
gen	Generate a standard virtual key
list	List virtual keys
inspect	Inspect a virtual key and its usage
rotate	Stage rotation for a virtual key
revoke	Revoke a virtual key by alias
gen-dev	Generate a developer key
gen-lead	Generate a team-lead key

Examples:

./scripts/acpctl.sh key gen alice --budget 10.00
./scripts/acpctl.sh key gen svc-claims --organization falcon-insurance --workspace claims-adjuster --budget 10.00
./scripts/acpctl.sh key list
./scripts/acpctl.sh key list --organization falcon-insurance
./scripts/acpctl.sh key inspect falcon-insurance--claims-adjuster--svc-claims__cc-1100 --organization falcon-insurance --workspace claims-adjuster --month 2026-02
./scripts/acpctl.sh key rotate falcon-insurance--claims-adjuster--svc-claims__cc-1100 --organization falcon-insurance --workspace claims-adjuster --dry-run
./scripts/acpctl.sh key revoke falcon-insurance--claims-adjuster--svc-claims__cc-1100 --organization falcon-insurance --workspace claims-adjuster

cert

TLS certificate lifecycle operations.

Subcommand	Summary
list	List tracked TLS certificates
inspect	Inspect one certificate
check	Validate certificate expiry and live TLS state
renew	Trigger controlled certificate reissuance
renew-auto	Install the automatic certificate renewal timer

Examples:

./scripts/acpctl.sh cert list
./scripts/acpctl.sh cert inspect --domain gateway.example.com
./scripts/acpctl.sh cert check --threshold-days 30
./scripts/acpctl.sh cert renew --domain gateway.example.com
sudo ./scripts/acpctl.sh cert renew-auto --env-file /etc/ai-control-plane/secrets.env

upgrade

Plan, validate, execute, and roll back host-first upgrades.

Subcommand	Summary
plan	Show the explicit supported upgrade plan
check	Validate the upgrade path, config migrations, and host convergence
execute	Execute the supported host-first upgrade workflow
rollback	Restore the pre-upgrade snapshots from a recorded upgrade run

Examples:

./scripts/acpctl.sh upgrade plan --from 0.0.9
./scripts/acpctl.sh upgrade check --from 0.0.9 --inventory deploy/ansible/inventory/hosts.yml --env-file /etc/ai-control-plane/secrets.env
./scripts/acpctl.sh upgrade execute --from 0.0.9 --inventory deploy/ansible/inventory/hosts.yml --env-file /etc/ai-control-plane/secrets.env
./scripts/acpctl.sh upgrade rollback --run-dir demo/logs/upgrades/upgrade-20260317T120000.000000000Z --inventory deploy/ansible/inventory/hosts.yml --env-file /etc/ai-control-plane/secrets.env

host

Host-first deployment and operations.

Subcommand	Summary
preflight	Validate host readiness
check	Run declarative host preflight/check mode
apply	Run declarative host apply/converge
failover-drill	Validate a customer-operated active-passive failover drill manifest and archive evidence
install	Install systemd service and automated backup timer
uninstall	Uninstall systemd service and automated backup timer
service-status	Show service and backup timer status
service-start	Start the systemd service
service-stop	Stop the systemd service
service-restart	Restart the systemd service

Examples:

./scripts/acpctl.sh host preflight
./scripts/acpctl.sh host check --inventory deploy/ansible/inventory/hosts.yml
./scripts/acpctl.sh host apply --inventory deploy/ansible/inventory/hosts.yml
./scripts/acpctl.sh host failover-drill --manifest demo/logs/recovery-inputs/ha_failover_drill.yaml
./scripts/acpctl.sh host install --service-user acp --backup-retention-keep 14
./scripts/acpctl.sh cert renew-auto --env-file /etc/ai-control-plane/secrets.env