CLI Reference

The al command-line tool brings AgentLattice governance to any deployment pipeline, shell script, or CI/CD workflow. No SDK required. If your agent runs as a bash script, a Go binary, a Rust service, or anything that can call a shell command, al makes it a governed agent.

Installation

npm install -g @agentlattice/cli

Or use npx without installing:

npx @agentlattice/cli whoami

Authentication

The CLI reads credentials from environment variables:

Set your agent API key once and every command authenticates automatically:

export AL_API_KEY="al_agent_your_key_here"

Action Types

The <action> argument in al gate and al execute is a semantic label that identifies what the agent is about to do. It is not a shell command. Your policies are written against these labels, so they need to be consistent across your codebase.

The convention is verb.resource or domain.action:

You can use any action type string your workspace agrees on. The key requirement is that the same action type is used consistently in both your agent code and your policy definitions.

Example: An agent running a shell command would submit shell.exec (not the actual command) and pass the command string in --metadata:

al gate shell.exec --metadata '{"command": "rm -rf /tmp/build"}'

The policy evaluates shell.exec. The metadata is recorded in the audit log but does not affect which policy matches.

Commands

al execute <action>

Submit an action for policy evaluation and return immediately without waiting for a human approval decision. Use this when you want to log the action and check for auto-allow/auto-deny policies, but the action does not need to wait for manual review.

al execute shell.exec --metadata '{"command": "ls /tmp"}'

If the policy requires human approval, al execute exits 0 and includes the approval_id in its output — it does not poll. Your code is responsible for checking the approval status later if needed.

Exit codes:

• 0 — allowed by policy, or submitted and pending approval
• 1 — denied by policy, or no matching policy found

For use cases where the action must not proceed until a human approves it, use al gate instead.

al gate <action>

Submit an action and block until it is resolved — approved, denied, or timed out. This is the right command for CI/CD pipelines and any workflow where you cannot proceed until you have explicit approval.

al gate deploy.production --metadata '{"sha": "abc123", "actor": "deploy-bot"}' \
  && kubectl apply -f deploy.yaml

If the action requires approval, al gate polls until an operator approves or denies the request from the dashboard. Exit codes:

• 0 — approved, proceed
• 1 — denied, or no matching policy found
• 2 — timeout (no decision within the configured window)

The && chaining means the deploy only runs if al gate exits 0. A denial or timeout stops the pipeline.

Timeout: Default is 30 minutes. Override with --timeout:

al gate deploy.production --timeout 1h
al gate db.migrate --timeout 10m

al whoami

Display the authenticated agent's identity, capabilities, and active enforcements.

al whoami

Agent:        deploy-bot
Workspace:    acme-corp
Capabilities: deploy.staging, deploy.production, rollback
Status:       monitoring

al status

Show the current circuit breaker state for the authenticated agent.

al status

al policies

List all policies that govern the authenticated agent.

al policies

al test

Dry-run an action against policies without creating an audit event. Useful for validating policy configuration before going live.

al test deploy.production --metadata '{"service": "api"}'

al audit

View the recent audit trail for the authenticated agent.

al audit --limit 20

al verify

Verify a delegation chain, confirming that each link is valid and unexpired.

al verify --chain-id "del_abc123"

al posture

Display the governance posture summary for the authenticated agent, including anomaly scores and compliance status.

al posture

al report

Report an anomaly or incident from the agent's perspective.

al report --type anomaly --description "Unexpected bulk data access pattern"

al register

Register a new agent in your workspace. Requires a service key (AL_SERVICE_KEY) rather than an agent key.

AL_SERVICE_KEY="al_svc_your_key" al register \
  --name "deploy-bot" \
  --capabilities "deploy.staging,deploy.production"

Returns the new agent's API key. This is shown once -- store it securely.

al export

Export all active policies for your workspace as a YAML manifest. The manifest can be checked into git and used with al import to promote policies across environments.

Requires a service key (AL_SERVICE_KEY).

# Print YAML manifest to stdout
AL_SERVICE_KEY="al_svc_your_key" al export

# Write to a file for git
AL_SERVICE_KEY="al_svc_your_key" al export --file policies.yaml

# Export as JSON instead of YAML
AL_SERVICE_KEY="al_svc_your_key" al export --format json --file policies.json

Options:

The exported manifest includes all active policies and circuit breaker configuration (informational). Circuit breaker settings are included for visibility but are not applied by al import.

al import

Import a policy manifest into your workspace. Policies in the manifest are created or updated. By default, policies not in the manifest are left unchanged.

Requires a service key (AL_SERVICE_KEY).

# Import from a file
AL_SERVICE_KEY="al_svc_your_key" al import --file policies.yaml

# Import from stdin (pipe from export)
al export | AL_SERVICE_KEY="al_svc_your_key" al import

# Preview what would change without applying it
AL_SERVICE_KEY="al_svc_your_key" al import --file policies.yaml --dry-run

# Full sync: deactivate policies not present in the manifest
AL_SERVICE_KEY="al_svc_your_key" al import --file policies.yaml --replace

Options:

Example output:

  + 2 added:
      block-prod-deploy
      require-approval-finance
  ~ 1 modified:
      audit-all-writes
  = 5 unchanged

Import complete — 2 added, 1 modified, 0 deleted
Manifest hash: sha256:a3f1b2c4...

Policy identity: Policies are matched by name, not action type. Two policies with the same action type but different names are treated as separate policies. This means you can safely have multiple policies per action type.

Every successful import writes a tamper-proof audit event recording what changed, including a SHA-256 hash of the full manifest.

Output Formats

By default, the CLI produces human-readable output. Add --json to any command for machine-parseable JSON output:

al whoami --json | jq '.capabilities'

Exit Codes

CI/CD Integration

GitHub Actions

- name: Gate production deploy
  env:
    AL_API_KEY: ${{ secrets.AL_API_KEY }}
  run: |
    npx @agentlattice/cli gate deploy.production \
      --metadata '{"sha": "${{ github.sha }}", "actor": "${{ github.actor }}"}'

Generic Pipeline

Any pipeline that supports shell commands can use al gate as a governance checkpoint:

#!/bin/bash
set -e

al gate deploy.production --metadata "{\"version\": \"$VERSION\"}"
# If we reach here, the action was approved
deploy_to_production

The set -e flag ensures the script exits on any non-zero exit code, which includes denials and timeouts.