Skip to main content

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

atmos aws credential-process --help

Usage​

atmos aws credential-process --identity=<name> [--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:

atmos auth env --format=credential-process --identity=<name> [--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 for the alias details.

Examples​

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

~/.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:

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

~/.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.

~/.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.

~/.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.

export ATMOS_CLI_CONFIG_PATH=/path/to/infrastructure
~/.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.

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 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 and aws/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, then retry the aws command:

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=<name> or atmos auth login --identity=<name>.

Output Contract​

The command prints one line of JSON in the AWS process-credential format:

{"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.

ATMOS_CLI_CONFIG_PATH

Directory that contains atmos.yaml. See 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 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=<name> 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: add --profile=<name> 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 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=<itself>. 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.

See Also​