Docs
⌘K

CLI: Policies, simulation and audit

Manage access policies, run access simulations and change previews (with CI exit codes), and read the audit trail with sov.

Updated Oct 16, 2026

sov sim run --fail-on critical exits with status 1 when a run finds critical problems, so it can stop a CI pipeline. Background: Simulate access before you ship.

sov sim run --fail-on critical
sov sim change --sql-file migrations/20261016_add_note.sql

sov policy

Guard policy engine commands

sov policy templates

List built-in SPL policy templates.

sov policy templates [OPTIONS]
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov policy list

List active policies in scope.

sov policy list [OPTIONS]
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov policy get

Fetch a policy by ID.

sov policy get [OPTIONS] POLICY_ID

Arguments and options

POLICY_IDtextrequired
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov policy upsert

Create or update a policy (tries create then update).

sov policy upsert [OPTIONS] POLICY_ID

Policies apply to the project in scope (--project or sov scope set).

Arguments and options

POLICY_IDtextrequired
--nametextrequired
--spltextrequired
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov policy delete

Delete (deactivate) a policy.

sov policy delete [OPTIONS] POLICY_ID

Arguments and options

POLICY_IDtextrequired
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov policy history

List policy version history.

sov policy history [OPTIONS] POLICY_ID

Arguments and options

POLICY_IDtextrequired
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov policy rollback

Rollback policy to a historical version.

sov policy rollback [OPTIONS] POLICY_ID

Arguments and options

POLICY_IDtextrequired
--versionintegerrequired
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov policy evaluate

Evaluate policy against an explicit context.

sov policy evaluate [OPTIONS] POLICY_ID

Arguments and options

POLICY_IDtextrequired
--contexttextrequired
JSON object
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov policy check

Preflight an action/resource against active Guard policies.

sov policy check [OPTIONS]

Arguments and options

--actiontextrequired
Action, e.g. sql:select or nosql:write
--resourcetextrequired
Resource name, table, or collection
--contexttextoptional
Optional JSON context object
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov policy simulate

Dry-run operations against the project's active Guard rules (nothing is changed).

sov policy simulate [OPTIONS]

Example: sov policy simulate --action PUBLISH --resource book:42 --context '{"actor": {"roles": ["librarian"]}, "realtime": {"prefix": "book"}}'

Arguments and options

--actiontextrequired
Action to test, e.g. PUBLISH, storage:upload, sql:insert (repeatable)
--resourcetextrequired
Resource for each --action: channel, bucket, table… (repeatable, same order)
--contexttextoptionaldefault {}
JSON context shared by every operation (actor roles, realtime prefix…)
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov sim

Scenario discovery, runs, and comparisons

sov sim discover

What a run would cover: personas, tables, collections, buckets, channels, functions, settings.

sov sim discover [OPTIONS]
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov sim runs

List simulation runs for the current project.

sov sim runs [OPTIONS]

Arguments and options

--limitintegeroptionaldefault 20
--offsetintegeroptionaldefault 0
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov sim get

Fetch one simulation run by ID.

sov sim get [OPTIONS] RUN_ID

Arguments and options

RUN_IDtextrequired
Simulation run ID
--expandflagoptional
Show nested run details
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov sim compare

Compare two simulation runs.

sov sim compare [OPTIONS] TARGET_RUN_ID BASELINE_RUN_ID

Arguments and options

TARGET_RUN_IDtextrequired
Run to inspect
BASELINE_RUN_IDtextrequired
Baseline run
--expandflagoptional
Show full comparison tree
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov sim run

Check who can do what in the live project — as visitors, your app's users and your team — with nothing written.

sov sim run [OPTIONS]

Arguments and options

--resourcetextoptional
Only this table, collection, bucket, channel or function
--actiontextoptional
Only this action, e.g. sql:delete
--roletextoptional
Only this persona: __guest__, __app_user__, app:<role> or a team role
--fail-ontextoptionaldefault critical
Exit 1 on findings at this level or worse: critical, warning, info, none
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.
sov sim run --fail-on critical
sov sim run --resource public.orders --role __guest__

sov sim change

Try a policy or SQL change before making it: who gains or loses access, what the script changes.

sov sim change [OPTIONS]

Nothing is written.

Arguments and options

--policy-filetextoptional
SPL of a new or replacement rule
--nametextoptional
Name of the draft rule
--replacestextoptional
Live policy id the draft stands in for
--disabletextoptional
Live policy id to leave out (repeatable)
--sqltextoptional
SQL script to try
--sql-filetextoptional
File with the SQL script to try
--fail-ontextoptionaldefault critical
Exit 1 on violations at this level or worse
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.
sov sim change --policy-file draft.spl --name "staff edit books" --fail-on warning
sov sim change --sql "alter table orders add column note text"

sov audit

Echo audit trail and simulations

sov audit append

Append an immutable audit entry.

sov audit append [OPTIONS]

Arguments and options

--event-typetextrequired
--actor-idtextrequired
--sourcetextrequired
--actiontextrequired
--resource-idtextoptional
--metadatatextoptional
JSON object
--ip-addresstextoptional
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov audit list

Query audit log entries.

sov audit list [OPTIONS]

Arguments and options

--actor-idtextoptional
--event-typetextoptional
--sourcetextoptional
--resource-idtextoptional
--limitintegeroptionaldefault 50
--offsetintegeroptionaldefault 0
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov audit verify

Verify audit hash-chain integrity.

sov audit verify [OPTIONS]
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov audit count

Return audit log entry count.

sov audit count [OPTIONS]
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov audit sim-run

Run an Echo phantom simulation.

sov audit sim-run [OPTIONS] SIMULATION_NAME OPERATIONS

Arguments and options

SIMULATION_NAMEtextrequired
OPERATIONStextrequired
JSON array operations
--contexttextoptional
JSON object
--include-execution-treeflagoptional
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

sov audit sim-plan

Preview an Echo simulation plan.

sov audit sim-plan [OPTIONS] SIMULATION_NAME OPERATIONS

Arguments and options

SIMULATION_NAMEtextrequired
OPERATIONStextrequired
JSON array operations
--contexttextoptional
JSON object
  • Also takes --profile, --org, --project and --env to act on another account, organization, project or environment.

Related

CLI referenceConnect your app
Something unclear or missing on this page?Tell us