# atmos secret import

Import brings existing secret values under management. From a **file** (`.env` or JSON), each key is written to **its own declared backend** — the `store:` or `sops:` named in that secret's [`secrets.vars`](/cli/configuration/secrets) declaration — with undeclared keys warned about and **skipped**. From an existing **store coordinate** (any `--from-*` flag), one declared secret's value is copied from where legacy [`!store`](/functions/yaml/store) usage left it into the declaration's computed coordinate — like `terraform import`, the source value is never modified or deleted. Use [`push`](/cli/commands/secret/push) instead if undeclared keys should be a hard error.

## Usage

```shell
# File mode: bulk-import declared keys from a .env/JSON file.
atmos secret import FILE [flags]

# Store-coordinate mode: adopt one declared secret's value from an existing store path.
atmos secret import NAME --from-stack=<segment> [--from-component=<segment>] [--from-store=<store>] [--from-key=<key>] [flags]
```

The positional argument is a `NAME` when any `--from-*` flag is given, and a `FILE` otherwise.

## Examples

```shell
# Import values from a .env file
atmos secret import secrets.env --stack=prod --component=api

# Import values from a JSON file
atmos secret import secrets.json --format=json --stack=prod --component=api

# Preview the import without writing anything
atmos secret import secrets.env --dry-run --stack=prod --component=api

# Import values piped in from standard input
cat secrets.env | atmos secret import - --stack=prod --component=api

# Migrate a legacy `!store app-secrets atmos shared client_secret` value:
# copy it from the old path into SHARED_CLIENT_SECRET's computed coordinate.
atmos secret import SHARED_CLIENT_SECRET \
  --from-stack=atmos --from-component=shared --from-key=client_secret \
  --stack=prod --component=api

# Verify the source is readable without writing anything
atmos secret import SHARED_CLIENT_SECRET --from-stack=atmos --dry-run \
  --stack=prod --component=api
```

## Arguments

- **`FILE`**

  The path to the file to import secret values from. Use `-` to read from standard input.
- **`NAME`**

  The declared secret to import into (store-coordinate mode, selected by any `--from-*` flag). Must be declared under the component's `secrets.vars`.

## Flags

- **`--stack` (alias `-s`)**

  The Atmos stack to operate on. **Required.**

  **Environment variable:** `ATMOS_STACK`
- **`--component` (alias `-c`)**

  The Atmos component whose declared secrets receive the values. **Required.**

  **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`
- **`--format`**

  The input format: `env` or `json`. Defaults to `env`. File mode only — combining it with `--from-*` flags is an error.
- **`--dry-run`**

  Preview without writing anything to the backend. In file mode, lists which values would be imported and which skipped; in store-coordinate mode, reads the source value to prove it exists and is accessible.
- **`--from-store`**

  The source store to copy from. Defaults to the declaration's own `store:`.
- **`--from-stack`**

  The source stack path segment. A **raw** segment transcribed from the legacy `!store` expression — it need not name a real Atmos stack.
- **`--from-component`**

  The source component path segment (raw, like `--from-stack`). Omit it for source paths that never had a component segment.
- **`--from-key`**

  The source key. Defaults to the secret name, for when the legacy key already matches the declaration.

:::note Lenient by design
Unlike [`push`](/cli/commands/secret/push), file-mode `import` does not fail on undeclared keys. It warns about each undeclared key, skips it, and reports a summary (for example, `5 imported, 2 skipped`). Store-coordinate mode targets one explicit `NAME`, so an undeclared name is a hard error there.
:::

:::tip Migrating from `!store`
The `--from-*` flags map one-to-one onto the legacy expression — `!store <store> <stack> <component> <key>` becomes `--from-store=<store> --from-stack=<stack> --from-component=<component> --from-key=<key>` — so migrating a line is a mechanical transcription. See [Migrating from `!store`](/cli/configuration/secrets#migrating-from-store) for the full recipe.
:::

## 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
- [Secret scopes](/cli/configuration/secrets#secret-scopes) — instance vs stack vs global storage