precinct CLI Reference

precinct 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.

precinct vs spike

precinct 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 precinct 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.

precinct <command> <subcommand> [flags]

precinct 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	Export DSAR packages and execute right-to-erasure for one SPIFFE identity
`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 and supporting-component health

Source code: cli/precinct/

precinct audit

Search and explain gateway audit decisions. Every gateway decision is recorded as a JSONL record with a decision ID that can be correlated with traces and compliance evidence.

Search audit records

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

# Search by relative time window
precinct audit search --last 24h

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

# Show only denied requests
precinct audit search --denied

Explain a specific decision

# Get a layer-by-layer explanation for a specific decision
precinct audit explain "d-29fa3b7c-8e91-4d12-a6c5-1f2e3d4a5b6c"

precinct 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)
precinct compliance collect --framework soc2

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

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

OpenSearch-backed evidence collection (HTTPS + mTLS)

export PRECINCT_OPENSEARCH_PASSWORD='<secret>'

precinct 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.

precinct gdpr

Handle GDPR data subject access requests (DSARs) and right-to-erasure workflows for one SPIFFE identity at a time.

# Export a DSAR package for one workload identity
precinct gdpr audit "spiffe://poc.local/agents/mcp-client/dspy-researcher/dev"

# Delete data for one workload identity (right to be forgotten)
precinct gdpr delete "spiffe://poc.local/agents/mcp-client/dspy-researcher/dev" --confirm

precinct identity

List SPIRE registration entries or register a new SPIFFE workload identity.

# List all registered identities
precinct identity list

# Register a new identity entry
precinct identity register my-agent \
  --selector docker:label:spiffe-id:my-agent \
  --confirm

precinct inspect

Inspect supporting-system state for diagnostics and troubleshooting.

# Show effective tool permissions for a SPIFFE identity
precinct inspect identity "spiffe://poc.local/agents/mcp-client/dspy-researcher/dev"

# Show active sessions and their risk scores
precinct inspect sessions

# Show rate limit bucket state
precinct inspect rate-limit

# Show circuit breaker state
precinct inspect circuit-breaker

precinct policy

List grants, dry-run policy checks, and hot-reload the gateway's tool registry and OPA policies.

# List grants from policy config files
precinct policy list "spiffe://poc.local/agents/test"

# Hot-reload policies on a running gateway
precinct policy reload

# Dry-run a policy decision without executing the real action
precinct policy test "spiffe://poc.local/agents/test" "tavily_search"

precinct repave

Inspect container repave state. This supports the third "R" in the 3 Rs Operating Doctrine: Repair, Rotate, Repave.

# Show last repave time and image/hash drift per container
precinct repave status

Destructive Operation

The current CLI exposes repave inspection only. Use your deployment automation to perform the actual rebuild or rollout.

precinct secret

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

# Bootstrap local dev SPIKE Nexus
precinct secret init

# List active token references
precinct secret list

# Store a secret by reference
precinct secret put "secrets/api-key-tavily" "$TAVILY_API_KEY" --confirm

# Issue a test SPIKE token
precinct secret issue "secrets/api-key-tavily"

precinct status

Display the health and operational status of the PRECINCT deployment.

# Overall gateway status
precinct status

# Single-component health
precinct status --component gateway
precinct status --component keydb
precinct status --component phoenix