agw CLI Reference

agw is the PRECINCT command-line tool for operations, compliance, auditing, identity management, and infrastructure lifecycle. It provides a single interface for everything an operator needs to manage a running PRECINCT deployment.

agw vs spike

agw is the PRECINCT project's CLI for operating the gateway and its surrounding infrastructure. The spike CLI is a separate tool that belongs to the SPIKE project and is used for interacting with the SPIKE secrets store directly. Both CLIs serve different purposes and are not interchangeable.

Overview

The agw CLI is organized into command groups, each covering a specific operational domain. It is built in Go and ships as a single binary alongside the gateway.

agw <command> <subcommand> [flags]

agw CLI command groups
Command	Domain	Description
`audit`	Audit & Forensics	Search, explain, and verify hash-chained audit logs
`compliance`	Compliance	Generate compliance reports, run control checks, export evidence
`gdpr`	Privacy	GDPR subject access requests, data deletion, consent management
`identity`	Identity	List, inspect, and manage SPIFFE workload identities
`inspect`	Diagnostics	Inspect gateway state, middleware chain, tool registry, and sessions
`policy`	Policy	Test, validate, and hot-reload OPA policy bundles
`repave`	Lifecycle	Tear down and rebuild the PRECINCT stack from trusted base images
`reset`	Lifecycle	Reset sessions, rate limit buckets, or circuit breaker state
`secret`	Secrets	Manage SPIKE token references and secret lifecycle
`status`	Monitoring	Display gateway health, middleware latency, and upstream status

Source code: POC/cmd/agw/

agw audit

Search, filter, and verify the hash-chained audit trail. Every gateway decision is recorded as a JSONL record with a cryptographic hash linking it to the previous record.

Search audit records

# Search by SPIFFE ID
agw audit search --identity "spiffe://poc.local/agents/mcp-client/dspy-researcher/dev"

# Search by time range
agw audit search --since "2026-02-20T00:00:00Z" --until "2026-02-21T00:00:00Z"

# Search by tool name
agw audit search --tool "tavily_search"

# Search by decision (allow/deny)
agw audit search --decision deny --limit 50

Explain a specific decision

# Get a human-readable explanation of why a request was allowed or denied
agw audit explain --decision-id "d-29fa3b7c-8e91-4d12-a6c5-1f2e3d4a5b6c"

Verify hash chain integrity

# Verify the entire audit trail has not been tampered with
agw audit verify --file /var/log/precinct/audit.jsonl

agw compliance

Collect evidence, generate reports, and extract control-specific proof artifacts from local audit files, Docker logs, or OpenSearch.

# Collect framework evidence package (writes timestamped directory)
agw compliance collect --framework soc2

# Generate formatted compliance report artifacts
agw compliance report --framework soc2 --output pdf

# Extract evidence for a single control
agw compliance evidence --control GW-AUTH-001 --format json

OpenSearch-backed evidence collection (HTTPS + mTLS)

export AGW_OPENSEARCH_PASSWORD='<secret>'

agw compliance collect \
  --framework soc2 \
  --audit-source opensearch \
  --opensearch-url https://opensearch.observability.svc.cluster.local:9200 \
  --opensearch-index 'precinct-audit-*' \
  --opensearch-ca-cert /certs/ca.crt \
  --opensearch-client-cert /certs/client.crt \
  --opensearch-client-key /certs/client.key

When --audit-source opensearch is selected, the CLI requires a CA cert, client cert/key, and password from environment to enforce secure evidence export.

agw gdpr

Handle GDPR data subject access requests (DSARs), data deletion (right to be forgotten), and consent management.

# Process a subject access request
agw gdpr sar --subject "user@example.com" --output sar-report.json

# Delete all data for a subject (right to be forgotten)
agw gdpr delete --subject "user@example.com" --confirm

# List consent records
agw gdpr consent list --subject "user@example.com"

agw identity

List and inspect SPIFFE workload identities known to the gateway.

# List all registered identities
agw identity list

# Show details for a specific identity
agw identity show "spiffe://poc.local/agents/mcp-client/dspy-researcher/dev"

# Check identity health (SVID expiration, rotation status)
agw identity health

agw inspect

Inspect the internal state of the gateway for diagnostics and troubleshooting.

# Show middleware chain status
agw inspect middleware

# Show tool registry contents
agw inspect tools

# Show active sessions and their risk scores
agw inspect sessions

# Show circuit breaker state for all upstreams
agw inspect circuits

agw policy

Test, validate, and manage OPA policy bundles used by the gateway.

# Run policy tests
agw policy test --bundle config/opa/

# Validate policy syntax
agw policy validate --bundle config/opa/

# Hot-reload policies on a running gateway
agw policy reload --gateway http://localhost:9090

# Simulate a policy decision without executing
agw policy eval --identity "spiffe://poc.local/agents/test" --tool "tavily_search"

agw repave

Tear down and rebuild the entire PRECINCT stack from trusted base images. This is the third "R" in the 3 Rs Operating Doctrine: Repair, Rotate, Repave.

# Repave the Docker Compose stack
agw repave --target compose

# Repave the Kubernetes deployment
agw repave --target k8s --namespace precinct

# Dry-run to preview what will be rebuilt
agw repave --target compose --dry-run

Destructive Operation

agw repave tears down running services before rebuilding. In production, coordinate repave operations with your deployment pipeline to ensure zero-downtime rotation.

agw secret

Manage SPIKE token references and inspect the secret lifecycle. This command interacts with the SPIKE secrets store through the gateway.

# List active token references
agw secret list

# Create a new token reference
agw secret create --name "api-key-tavily" --value "$TAVILY_API_KEY"

# Rotate a token reference
agw secret rotate --name "api-key-tavily"

# Inspect reference metadata (without revealing the value)
agw secret inspect --name "api-key-tavily"

agw status

Display the health and operational status of the PRECINCT deployment.

# Overall gateway status
agw status

# Example output:
# Gateway:       healthy (uptime: 3d 14h 22m)
# SPIRE:         connected (trust domain: poc.local)
# OPA:           loaded (42 policies, last reload: 2m ago)
# KeyDB:         connected (rate limit buckets: 156 active)
# Upstreams:     3/3 healthy
# Audit trail:   12,847 records (hash chain: verified)
# Active sessions: 23

# Per-middleware latency (live)
agw status latency

# Upstream health details
agw status upstreams