Skip to main content

atmos policy

The policy commands support policy authoring. They read literal policy documents from policy.d/, or the directory selected by ATMOS_POLICY_DIR, without loading atmos.yaml, discovering stacks, contacting CI APIs, installing tools, or executing hooks.

atmos policy check
atmos policy list
atmos policy schema function
atmos policy test tests/cases.json

check displays a human-readable summary by default; use --format json for JSON on stdout. list, schema, and test produce JSON on stdout. Invalid configuration, unsupported input kinds, malformed fixtures, and failed expectations return a nonzero exit status. They deliberately do not enforce command admission against themselves, so a broken or denying bundle can still be inspected. Normal operational commands retain their policy gates.

check​

atmos policy check validates document fields, CEL/Starlark compilation, unique rule identities, selectors, CI requirements, approval specifications, hook references and definitions, and tool-pin consistency. It checks configuration, not whether an operation would be allowed. It does not require installed hook executables or CI credentials. An absent or empty policy bundle is an error.

The default summary reports successful validation and the rule and hook counts on stderr. It uses terminal styling when available and degrades to plain text when redirected or colors are disabled. For scripts, request JSON explicitly:

atmos policy check --format json
{
  "hooks": 0,
  "rules": 1,
  "valid": true
}
--format / -f
Output format: text (default), json, or yaml. Structured output is written to stdout without the human-readable summary.
ATMOS_POLICY_CHECK_FORMAT
Environment equivalent of --format. The command-line flag takes precedence. ATMOS_POLICY_FORMAT is a fallback when ATMOS_POLICY_CHECK_FORMAT is unset.
atmos policy check --help

list​

atmos policy list prints the loaded definitions in deterministic order, including rule IDs, input kinds, expressions, selectors, parameters, and effects. This is a view of the configured bundle; it does not resolve remote libraries or execute predicates. Treat literal policy parameters as potentially private when sharing the output.

schema​

input-kind
One of command, component.command, function, source, operation, plugin, terraform.plan, or atmos.affected. Prints the JSON Schema for input, rather than the entire request envelope. Terraform retains its native plan shape. The plugin kind describes the input of on: plugin rules; see plugin policies.

Use atmos ci context to inspect the provider-native CI snapshot. A schema describes available fields; it does not attest that a particular command collected them.

test​

cases.json
A nonempty JSON array of named fixtures, at most 16 MiB. Each fixture supplies a complete policy request and the expected aggregate decision. The format matches the policy library's tests/cases.json files.
[
  {
    "name": "deny exec",
    "request": {
      "kind": "function",
      "input": {"name": "exec", "engine": "yaml", "provenance": "local", "source_file": "example.yaml"}
    },
    "status": "deny"
  }
]

Statuses are allow, deny, not_applicable, awaiting_approval, and error. A false predicate normally produces not_applicable. Optional error values are input_unavailable or evaluation. Use hooks to assert the selected hook requirements and approvals to assert approval requirements. Approval fixtures test the outstanding requirement, not live review verification. No network calls or hook execution occur. Fixtures contain supplied data and cannot authorize a real operation.

Explain an operation​

atmos terraform plan vpc -s prod --explain
atmos terraform plan vpc -s prod --dry-run --explain
--explain
Add policy diagnostics to stderr while preserving normal command execution, enforcement, and stdout. Reports reached gates, rule outcomes, selector exclusions, approval verification, selected hook requirements, and configured input kinds never reached. Input values and function arguments are not printed.
ATMOS_EXPLAIN
Environment equivalent of --explain. The command-line flag takes precedence. When --explain is set, Atmos exports ATMOS_EXPLAIN=true to the processes it starts, so nested Atmos commands run by scripts, steps, workflows, and custom commands report their own policy diagnostics too.

--explain is not a preview flag. Combine it with a command's existing --dry-run when supported. Dry-run cannot evaluate a saved-plan policy without a real plan; the diagnostic explicitly reports that no saved-plan verdict was obtained. A failed earlier gate can prevent later gates from being reached.

Try it out​

Copy the example into a new directory and make it your own:

atmos init examples/policies
cd policies

Only Atmos is required. Validate the rule and run its offline fixtures, then follow the README to compare an allowed command with an intentional denial.

atmos policy check
atmos policy list
atmos policy test tests/cases.json
Explore the example →Initialization and repository settings