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

`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:

```shell
atmos policy check --format json
```

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

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

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

## Try it out

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.

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