@trigguard/cli

@trigguard/cli

Execution authorization for AI agents and automated systems.

Operator CLI for the execution gateway: authorize, verify receipts, login, policy, and escalation.

npx trigguard demo
npm install -g @trigguard/cli
tg login

TrigGuard authorizes execution. It does not execute your deploy, payment, or tool call.

Install

npm install -g @trigguard/cli
tg --help

Monorepo development:

npm run build -w @trigguard/cli
node packages/trigguard-cli/dist/index.js --help

Commands

export TRIGGUARD_GATEWAY_URL=https://your-run-url.run.app
export TRIGGUARD_BEARER="$(gcloud auth print-identity-token --audiences=$TRIGGUARD_GATEWAY_URL)"

trigguard authorize --surface deploy.release --json
trigguard verify ./receipt.json --json

Escalation lifecycle (tg escalation)

Control-plane session required (tg login). JSON (--json) or table output.

tg escalation list [--status PENDING] [--org <orgId>] [--json]
tg escalation show <escalationId> [--org <orgId>] [--json]
tg escalation status <escalationId> [--org <orgId>] [--json]
tg escalation approve <escalationId> [--reason ...] [--org <orgId>] [--json]
tg escalation reject <escalationId> [--reason ...] [--org <orgId>] [--json]
tg escalation cancel <escalationId> [--org <orgId>] [--json]
tg escalation watch <escalationId> [--interval 5] [--org <orgId>] [--json]

Exit codes: 0 ok, 1 error, 2 not found, 3 conflict, 20 still pending (watch).

Provider mode (vendor JSON → gateway)

Map a vendor-shaped payload with a built-in adapter (packages/trigguard-providers), then authorize:

trigguard authorize --provider stripe --input ./payment.json --json
cat payment.json | trigguard authorize --provider stripe --input - --json

Use --surface + optional --context <file.json> when you already have canonical fields and do not need mapAction.

Or TRIGGUARD_USE_GCLOUD=1 to obtain the identity token via gcloud automatically.

CI vs local

Environment	Auth
GitHub Actions	TrigGuard-AI/authorize@v1 (OIDC → GCP)
Local / scripts	TRIGGUARD_BEARER or TRIGGUARD_USE_GCLOUD=1

Local execution authority (dev)

npm run build
node dist/index.js dev --port 8787
# or: npx trigguard dev

• trigguard doctor — Node version, monorepo detection, optional /health on 127.0.0.1:8787
• trigguard verify-receipt <file.json> --public-key <hex> — offline verify for Execution Authority flat JSON (same as sdk/node verifyReceipt)
• Optional --swift uses tg_execution_authority when TG_AUTHORITY_PRIVATE_KEY and a binary are available; otherwise the CLI falls back to the Node mock.

See ../../docs/getting-started/local-authority.md.

Offline receipt verification

trigguard verify uses @trigguard/receipt-verify. When you pass a known authority public key, verification is fully offline (no /.well-known fetch):

trigguard verify ./receipt.json --public-key <64-hex-ed25519-raw-or-pem>
trigguard verify ./receipt.json --public-key-file ./authority.pem

Precedence: --public-key → --public-key-file → keys from --keys-url / TRIGGUARD_KEYS_URL (with optional bearer for gated endpoints).

For Execution Authority /decide-shaped receipts, this matches the same canonical signing material as sdk/node / Swift.