# atmos.secret

The `atmos.secret` function runs `atmos secret` through the current Atmos executable. Use it to check that
declared secrets are initialized, provision or rotate them, and read their values from automation.

## Usage

```python
atmos.secret(
    *positionals,
    flags = {},
    args = [],
    working_directory = ...,
    env = ...,
    output = "stream",
    check = True,
)
```

## Subcommands

Pass the subcommand and any positional arguments as strings before the keyword arguments. The call
`atmos.secret("validate", flags = {"stack": "prod", "component": "api"})` runs
`atmos secret validate --stack=prod --component=api`.

| Subcommand | Purpose |
| --- | --- |
| [`list`](/cli/commands/secret/list) | List declared secrets and their initialization status. |
| [`get`](/cli/commands/secret/get) | Retrieve a declared secret's value. |
| [`set`](/cli/commands/secret/set) | Set a declared secret's value (create or update). Also available as `add`. |
| [`delete`](/cli/commands/secret/delete) | Remove a declared secret's value from its backend. Also available as `rm` and `unset`. |
| [`init`](/cli/commands/secret/init) | Provision (and rotate) declared secrets. |
| [`import`](/cli/commands/secret/import) | Import existing secret values, bringing them under management. |
| [`pull`](/cli/commands/secret/pull) | Download declared secrets to a local file for development. |
| [`push`](/cli/commands/secret/push) | Upload secret values from a local file. |
| [`validate`](/cli/commands/secret/validate) | Validate that all required declared secrets are initialized. |
| [`keygen`](/cli/commands/secret/keygen) | Generate key material for a secrets vault whose backend supports it. |
| [`exec`](/cli/commands/secret/exec) | Run a command with declared secrets injected as environment variables. |
| [`shell`](/cli/commands/secret/shell) | Launch an interactive shell with declared secrets in the environment. |

See the [`atmos secret` command reference](/cli/commands/secret/usage) for the complete list of subcommands and
flags.

## Arguments

- **`*positionals`**

  (Optional) Strings placed on the command line right after `secret`, in order: the subcommand and its
  positional arguments, such as the secret name. For `set`, the name and value can be one string in the form
  `NAME=VALUE`. Every value must be a string.
- **`flags`**

  (Optional) A dictionary of command-line options; see
  [flag translation](/functions/automation/atmos.run#flag-translation). A bare key such as `"stack"` becomes
  `--stack`, and registered shorthands such as `"s"` and `"c"` resolve to `--stack` and `--component`.
  Common keys for this command are `"stack"`, `"component"`, `"identity"`, `"format"`, and `"force"`.
- **`args`**
  (Optional) A list or tuple of strings appended after the flags.
- **`working_directory`, `env`, `output`, `check`**

  (Optional) See [`atmos.run`](/functions/automation/atmos.run#arguments) for process options and defaults.

Options other than the positionals are keyword-only.

## Returns

A result with `stdout`, `stderr`, and `exit_code`. See [`atmos.run`](/functions/automation/atmos.run#returns) for output and error behavior.

## Examples

### Fail early when a secret is missing

The `validate` subcommand exits with code 1 when a required secret has no value.

```python
check_result = atmos.secret(
    "validate",
    flags = {"stack": "prod", "component": "api"},
    output = "capture",
    check = False,
)
if check_result.exit_code != 0:
    fail("Required secrets are missing:\n" + check_result.stderr)
ui.success("All required secrets are initialized.")
```

### Report secret status as data

```python
listing = atmos.secret("list", flags = {"stack": "prod", "component": "api", "format": "json"}, output = "capture")
secrets = json.decode(listing.stdout)
print(secrets)
```

### Set a secret from a script

This example reads the value from the [`env`](/functions/automation/env) inputs declared by the step.

```python
atmos.secret(
    "set",
    "DATADOG_API_KEY=" + env["DATADOG_API_KEY"],
    flags = {"stack": "prod", "component": "api", "force": True},
    output = "capture",
)
```

Use `output = "capture"` when a command handles sensitive values so the process output is not shown live.

## Notes

:::note
The `atmos secret` command is experimental, and the wrappers keep its native behavior, including authentication through
the backend identity. Without `--force`, `set` asks for confirmation before it overwrites an existing value, so scripts
that update secrets pass `force`. The `shell` subcommand starts an interactive shell and needs a terminal. It is not a
good fit for a script. The `get` command redacts its displayed value unless masking is turned off.
:::

## Related

- [`atmos.run`](/functions/automation/atmos.run) runs any Atmos command from an argument list.
- [`atmos secret`](/cli/commands/secret/usage) documents every subcommand and flag.
- [Atmos Automation Language](/automation/language) and the [script step](/steps/type/script#calling-atmos-commands)