# atmos secret pull

Download the initialized declared secrets for a stack and component to a local `.env` or JSON file. This is intended to make secret values available to local development tooling. Values are written to the target file in cleartext, so the output is for **local development only** — never commit it or share it.

## Usage

```shell
atmos secret pull [flags]
```

Without `--component`, only the stack's stack-scoped and global secrets are downloaded; instance-scoped secrets are never included. Their declarations must agree across components, otherwise `--component` is required. See [Secret scopes](/cli/commands/secret/usage#secret-scopes).

## Examples

```shell
# Print secrets to stdout in env format
atmos secret pull --stack=prod --component=api

# Only the stack-scoped and global secrets, no component
atmos secret pull --stack=prod

# Write secrets to a local .env file
atmos secret pull --stack=prod --component=api --output=.env

# Write secrets as JSON
atmos secret pull --stack=prod --component=api --format=json --output=secrets.json

# Pull using a specific identity for the backend
atmos secret pull --stack=prod --component=api --identity=aws/prod-secrets
```

## Arguments

- **n/a** — No positional arguments.

## Flags

- **`--stack` (alias `-s`)** — The Atmos stack to operate on. **Required.**

  **Environment variable:** `ATMOS_STACK`
- **`--component` (alias `-c`)** — The Atmos component whose declared secrets are downloaded. Omit it to download only the stack's stack-scoped and global secrets (see [Secret scopes](/cli/commands/secret/usage#secret-scopes)); **required** for instance-scoped secrets.

  **Environment variable:** `ATMOS_COMPONENT`
- **`--type`** — The component type (`terraform`, `helmfile`, `packer`, or `ansible`). Used to disambiguate when a component name exists in more than one type.
- **`--identity` (alias `-i`)** — The identity to use when accessing the secret backend.

  **Environment variable:** `ATMOS_IDENTITY`
- **`--output` (alias `-o`)** — The output file to write secrets to. Defaults to standard output.
- **`--format`** — The output format: `env` or `json`. Defaults to `env`.

:::warning Local development only
`pull` writes secret values in cleartext to the target file. Use it only for local development, and never commit the resulting file to version control.
:::

## See Also

- [atmos secret](/cli/commands/secret/usage) — Overview of the secret command group
- [`!secret` YAML function](/functions/yaml/secret) — Resolve declared secrets at runtime