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

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

These commands 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.

## 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
  , 
  terraform.plan
  , or

  atmos.affected
  . Prints the JSON Schema for 
  input
  , rather than the
  entire request envelope. Terraform retains its native plan shape.

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.

```json
[
  {
    "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

```shell
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.