aasm policy

Manage governance policies — apply new versions, inspect history, roll back, diff, simulate, validate locally, and view effective policy.

Synopsis

aasm policy <SUBCOMMAND> [OPTIONS]

All subcommands accept the global options.

aasm policy apply

Apply a policy YAML file and save it to version history.

aasm policy apply ./policies/prod.yaml --applied-by alice@example.com

Policy applied successfully.
  Version:    9f2c1a
  Timestamp:  2026-06-09T14:00:00Z
  Active:     true
  Rules:      12

aasm policy history

List recent policy versions.

aasm policy history -n 5

aasm policy rollback

Roll back to a previous policy version, making it active again.

The stored version is re-applied through the running API server (the same POST /api/v1/policies as aasm policy apply), so the server’s active policy changes and the rollback is added to its history as a new version applied by api. The command prints Rolled back successfully. only when the server’s reply to that apply says the same version is active. If the version is not in the local history or is ambiguous, or the server cannot be reached or refuses the policy, it exits non-zero and writes nothing.

History is stored in ${AA_DATA_DIR:-~/.aa}/policy-history (directory 0700; new files 0600, older files keep their mode until rewritten). apply through a local server and history, get, diff and rollback share it only on the same host with the same AA_DATA_DIR/HOME; a remote server reached with --api-url, or a daemon started with a different environment, has its own store. A restarted local server re-installs the newest entry as its active policy, and refuses to start if it cannot (the error names the directory and file; move aside only that entry’s .meta.json and .yaml to recover). With $AA_POLICY set, that policy stays active and history is not reinstalled, so the active-policy view may differ.

The policy file the gateway watches ($AA_POLICY, or the generated bootstrap file) is re-read on every change, but only a change to that file’s content replaces the live policy: an applied or rolled-back policy stays enforced until the file’s content next changes, and a later real edit to the file overrides it.

• Saving the file again with identical content does not override an applied policy; change the content to do that.
• An invalid or blank edit is ignored. Restoring the previous content afterwards is not a change either, so the applied policy keeps winning.
• A directory of policy files (cascade mode) has its own reload path, which this behaviour does not cover; a change in the directory can replace an applied policy.
• With $AA_POLICY set, a restart loads that file and drops the applied policy (history is not reinstalled, see above).
• A file edit that lands in the same instant as aasm policy apply can win the race; aasm policy get then reports the applied version while the edited file is enforced.

Every read of a history entry (get, diff, rollback and the start-up restore) verifies that its YAML still hashes to the SHA-256 recorded in its metadata and refuses a modified entry with an integrity error naming the directory and file. Entries written by earlier release candidates hash the same way. This detects a changed YAML only; it does not stop someone who rewrites both files.

aasm policy rollback 9f2c1a

aasm policy diff

Show a colorized unified diff between two policy versions. Colors are suppressed when stdout is not a TTY.

aasm policy diff 9f2c1a 7ab310

aasm policy simulate

Simulate a policy against historical audit events or live traffic without enforcing it. Exits non-zero if the simulation detects any violation, so it can gate a CI pipeline.

aasm policy simulate --policy ./candidate.yaml --against ./audit/session.jsonl

Simulation Report
--------------------------------------------------
Total events:       412
Allowed:            409
Denied:             3
Approval required:  0
Budget impact:      $0.00

EVENT#   ACTION               DECISION     REASON
----------------------------------------------------------------------
0        file_write           deny         block-system-paths

The command exits non-zero when the report has any denied or errored outcome (so it can gate CI). The EVENT# table is printed only when there are flagged outcomes, and the Budget impact line only when a budget impact is computed.

aasm policy validate

Validate a policy YAML file locally (no apply, no gateway contact). Exits 0 when valid, 1 with error details on stderr otherwise.

“Valid” means the file parses and passes the schema checks; it does not mean a runtime in governed lease mode (AA_LEASE_POLICY) will admit every tool. For each tool that such a runtime would deny on every call (a tool with no capabilities, or a capability with no matching authority.leases entry) the command prints a warning: on stderr naming the tool and what to add. Warnings never change the exit status. They are computed by the runtime’s own lease decision, so they cannot disagree with it, and they are only produced by builds that include governed lease mode. They cover only the tools listed under tools:, judged for the tool-call action type; other action types are not assessed.

aasm policy validate ./policies/prod.yaml

Policy is valid: ./policies/prod.yaml

aasm policy get

Show the currently active policy YAML, or a specific version.

aasm policy get --version 9f2c1a

aasm policy list

List all policies deployed to the governance runtime. Takes no flags of its own (uses the global --output).

aasm policy list --output json

NAME      STATUS     UPDATED_AT               RULES
9f2c1a    Active     2026-06-09T14:00:00Z     12
7ab310    Inactive   2026-06-01T09:30:00Z     11

aasm policy show

Show an agent’s effective policy view. By default prints the agent identity; add a flag to expand into the capability cascade or budget rollup.

aasm policy show a1b2c3… --show-permissions

Capability        Effective   Granted by      Denied by
search            Allow       team:research   —
file_write        Deny        —               org

Last updated: 2026-11-06 by Chisanan232