# atmos aws credential-process Print temporary AWS credentials for any Atmos identity in the JSON format that the AWS CLI and AWS SDKs expect from a [`credential_process`](https://docs.aws.amazon.com/sdkref/latest/guide/feature-process-credentials.html) profile. Point a profile in `~/.aws/config` at this command and tools such as `aws`, `boto3`, or the Terraform AWS provider can use your Atmos identities from any directory, without wrapping each call in `atmos auth exec`. ## Usage ```shell atmos aws credential-process --identity= [--min-validity=15m] ``` The `--identity` flag is required unless exactly one identity in `atmos.yaml` is marked `default: true`. The value of `--min-validity` must include a unit, for example `15m` or `1h`. The same output is available through `atmos auth env`, which honors the same `--min-validity` flag and `ATMOS_AWS_CREDENTIAL_PROCESS_MIN_VALIDITY` environment variable and resolves the identity the same way: ```shell atmos auth env --format=credential-process --identity= [--min-validity=15m] ``` Combining `atmos auth env --format=credential-process` with `--login=false` is an error. This format has to authenticate whenever the cached credentials are missing or about to expire, so asking it not to authenticate contradicts the format. See [`atmos auth env`](/cli/commands/auth/env) for the alias details. ## Examples ```shell # Print credentials for an identity atmos aws credential-process --identity=app-sandbox-1 # Refresh credentials that expire within the next 30 minutes atmos aws credential-process --identity=app-sandbox-1 --min-validity=30m # Pretty-print the result atmos aws credential-process --identity=app-sandbox-1 | jq . # Equivalent output through the auth env alias atmos auth env --format=credential-process --identity=app-sandbox-1 ``` ## Using Atmos Identities from the AWS CLI Add a profile to `~/.aws/config` whose `credential_process` calls Atmos. The AWS CLI runs that command each time it needs credentials. ```ini title="~/.aws/config" [profile app-sandbox-1] credential_process = atmos --chdir=/path/to/infrastructure aws credential-process --identity=app-sandbox-1 region = us-east-1 ``` Then use the profile from any directory: ```shell aws sts get-caller-identity --profile=app-sandbox-1 aws s3 ls --profile=app-sandbox-1 ``` If the identity is defined in an [Atmos profile](/cli/configuration/profiles), add Atmos's own `--profile` flag to the `credential_process` line. It selects the Atmos configuration profile, which is not the same as `aws --profile`, and it can also be set with `ATMOS_PROFILE`: ```ini title="~/.aws/config" [profile plat-dev-terraform] credential_process = atmos --chdir=/path/to/infrastructure --profile=devops aws credential-process --identity=plat-dev/terraform ``` Here `aws --profile=plat-dev-terraform` picks the AWS profile above, and `--profile=devops` tells Atmos which Atmos profile to load. Atmos locates `atmos.yaml` the usual way, so you can pick whichever of these fits your setup: - **`--chdir=/path/to/project` (alias `-C`)** The most robust option. Atmos behaves exactly as if you ran the command from the project directory, so relative paths in `atmos.yaml` resolve as expected. ```ini title="~/.aws/config" credential_process = atmos --chdir=/path/to/infrastructure aws credential-process --identity=app-sandbox-1 ``` - **`--config-path=/path/to/project`** Point Atmos at the directory that contains `atmos.yaml`. ```ini title="~/.aws/config" credential_process = atmos --config-path=/path/to/infrastructure aws credential-process --identity=app-sandbox-1 ``` - **`ATMOS_CLI_CONFIG_PATH`** Set the environment variable in the shell that runs `aws`, and keep the profile short. ```shell export ATMOS_CLI_CONFIG_PATH=/path/to/infrastructure ``` ```ini title="~/.aws/config" credential_process = atmos aws credential-process --identity=app-sandbox-1 ``` - **Global `~/.atmos/atmos.yaml`** Define the identities in the global Atmos configuration. No path flags are needed because Atmos finds the file from any directory. :::tip Windows paths Quote any path that contains spaces, for example `credential_process = atmos --chdir="C:\Users\me\My Project" aws credential-process --identity=app-sandbox-1`. ::: ## How It Works 1. Atmos resolves the identity from `--identity`, then the `ATMOS_IDENTITY` environment variable, then the single identity marked `default: true` in `atmos.yaml`. The interactive identity selector is never shown, even in a terminal. The AWS CLI captures the command's output, so a prompt would be invisible and the `aws` command would hang. Without an identity, the command fails immediately and names the fix. 2. If cached credentials for the identity have more than `--min-validity` of lifetime left (default 15 minutes), Atmos prints them immediately without any network call. Credentials with less time left than that are refreshed even though they have not expired yet. Raise `--min-validity` to refresh earlier, for example for a long-running job. The AWS CLI runs `credential_process` once per CLI invocation, so reusing valid credentials keeps every `aws` command fast. 3. Otherwise Atmos authenticates the identity and prints the new credentials. This is the authentication that [`atmos auth login`](/cli/commands/auth/login) performs, minus the integrations: the command skips automatic integrations such as ECR login and EKS kubeconfig updates, because it runs as a non-interactive helper. Run `atmos auth login` when you want those. Identities that keep their own credential cache, such as [`aws/user`](/cli/configuration/auth/identities#user-break-glass) and [`aws/credential-process`](/cli/configuration/auth/identities#credential-process), are included: a cached session that has less than `--min-validity` left is refreshed instead of reused. 4. If the credential source still issues credentials that expire sooner than `--min-validity`, for example a helper that only mints 20-minute credentials, Atmos prints what it received. It never loops or fails because of the shorter lifetime. 5. Atmos prints exactly one JSON document to stdout. Logs and notices go to stderr, so they never corrupt the output the AWS CLI parses. ### Expired Sessions and Prompts The AWS CLI captures this command's stderr, so Atmos cannot show a prompt, a device code, or a browser instruction while it runs under the AWS CLI. Atmos only prompts when both stdin and stderr are terminals, so when the identity needs an interactive login, such as an expired AWS SSO session or an MFA code, the command fails immediately instead of hanging. The error explains why and hints at the fix. Log in first with [`atmos auth login`](/cli/commands/auth/login), then retry the `aws` command: ```shell atmos auth login --identity=app-sandbox-1 aws s3 ls --profile=app-sandbox-1 ``` For AWS SSO, Atmos keeps its own token cache, so `aws sso login` does not help. Use `atmos auth login --provider=` or `atmos auth login --identity=`. ## Output Contract The command prints one line of JSON in the [AWS process-credential format](https://docs.aws.amazon.com/sdkref/latest/guide/feature-process-credentials.html): ```json {"Version":1,"AccessKeyId":"ASIA...","SecretAccessKey":"...","SessionToken":"...","Expiration":"2026-10-02T18:30:00Z"} ``` - The version field, `Version`, is always `1`. - Both `AccessKeyId` and `SecretAccessKey` are always present. - Long-lived keys omit `SessionToken` and `Expiration`. - The expiration is an RFC3339 timestamp in UTC. The credentials are printed unmasked because delivering them to the caller is the purpose of the command. Secret masking still applies to all other Atmos output. ## Arguments - **n/a** No positional arguments. ## Flags - **`--identity` (alias `-i`)** Name of the identity to print credentials for. If omitted, Atmos uses the `ATMOS_IDENTITY` environment variable, then the single identity marked `default: true` in `atmos.yaml`. The identity must be an AWS identity. This command never opens the interactive identity selector, so `--identity` without a value and `--identity=false` are errors, and the command fails immediately when no identity can be resolved. - **`--min-validity`** Minimum remaining lifetime for cached credentials to be reused. When the cached credentials expire sooner than this, Atmos authenticates again before printing, including for identities that cache their own credentials. If the source cannot issue credentials that last this long, Atmos prints the longest-lived credentials it received. Default: `15m`. The value must include a unit, for example `30m` or `1h`. Use `0` to reuse any credentials that have not expired. Environment variable: `ATMOS_AWS_CREDENTIAL_PROCESS_MIN_VALIDITY`. ## Environment Variables - **`ATMOS_IDENTITY`** Identity to print credentials for when `--identity` is not passed. Set it in the shell that runs `aws`, or rely on a single `default: true` identity instead. - **`ATMOS_AWS_CREDENTIAL_PROCESS_MIN_VALIDITY`** Environment variable equivalent of `--min-validity`, for example `30m`. The flag takes precedence. - **`ATMOS_PROFILE`** Atmos configuration profile to load, equivalent to Atmos's `--profile` flag. Use it when the identity is defined in an [Atmos profile](/cli/configuration/profiles). - **`ATMOS_CLI_CONFIG_PATH`** Directory that contains `atmos.yaml`. See [Using Atmos Identities from the AWS CLI](#using-atmos-identities-from-the-aws-cli). ## Using Credential Helpers with Atmos This command produces credentials for the AWS CLI. The opposite direction, running an existing external helper such as `okta-aws-cli` or `aws-vault` and using its credentials in Atmos, is handled by the [`aws/credential-process`](/cli/configuration/auth/identities#credential-process) identity kind. The two combine: Atmos can run your helper, then hand the credentials to the AWS CLI through this command. ## Troubleshooting - **Verify the profile** Run `aws sts get-caller-identity --profile=app-sandbox-1`. If it prints the expected account and role, the profile is wired correctly. - **Run the command directly** Run `atmos --chdir=/path/to/infrastructure aws credential-process --identity=app-sandbox-1` in a terminal to see any error output the AWS CLI would otherwise hide. - **The command says an identity is required** The command found no identity to use. Pass `--identity=` in the profile's `credential_process` line, set `ATMOS_IDENTITY`, or mark one identity `default: true`. Run `atmos auth list` to see the available identities. The identity may be defined in an [Atmos profile](/cli/configuration/profiles): add `--profile=` to the `credential_process` line. - **The command asks you to log in** The identity's session expired, and Atmos cannot prompt while the AWS CLI captures its output. Run `atmos auth login --identity=app-sandbox-1` in a terminal, then retry. - **The command times out** A helper behind an [`aws/credential-process`](/cli/configuration/auth/identities#credential-process) identity must finish within one minute. A helper that waits for an MFA code or a browser login cannot complete under the AWS CLI. Authenticate it first in a terminal with `atmos auth login`, so that its credentials are cached for later calls. Atmos only reuses helper credentials that include an `Expiration`. - **Recursion error** A `credential_process` helper called back into Atmos for an identity that was already being resolved. This happens when an `aws/credential-process` identity runs `atmos aws credential-process --identity=`. Point the helper at a different identity. - **Atmos cannot find atmos.yaml** The AWS CLI runs the command from your current directory. Add `--chdir=/path/to/infrastructure` to the profile, or use one of the other [configuration discovery options](#using-atmos-identities-from-the-aws-cli). ## See Also - [Auth Env Command](/cli/commands/auth/env) — Export credentials as environment variables, including the `credential-process` format - [Auth Login Command](/cli/commands/auth/login) — Authenticate with identities - [Auth Identities](/cli/configuration/auth/identities) — Configure identities, including `aws/credential-process` - [AWS EKS Token Command](/cli/commands/aws/eks-token) — The equivalent exec credential plugin for `kubectl`