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

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

See the atmos secret command reference 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. 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 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 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.

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

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 inputs declared by the step.

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 runs any Atmos command from an argument list.
• atmos secret documents every subcommand and flag.
• Atmos Automation Language and the script step