atmos.auth

The atmos.auth function runs atmos auth through the current Atmos executable. Use it to log in with an identity, inspect authentication status, export temporary credentials, and run commands under an identity from automation.

Usage

atmos.auth(
    *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.auth("login", flags = {"identity": "prod"}) runs atmos auth login --identity=prod.

Subcommand	Purpose
login	Authenticate with a configured identity.
whoami	Show the current authentication status.
list	List authentication providers and identities.
validate	Validate the authentication configuration.
env	Export temporary cloud credentials as environment variables.
exec	Run a command with the identity's environment variables.
shell	Launch an interactive shell with the identity's environment variables.
console	Open the cloud provider web console in a browser.
logout	End a session by clearing its stored data.
user	Manage cloud provider user credentials in the local keychain, with configure.

See the atmos auth command reference for the complete list of subcommands and flags. The auth command is experimental, so some calls print an experimental notice on standard error.

note

The shell and console subcommands, and user configure, are interactive or open a browser, so they suit a person at a terminal more than a script. A login that needs a browser or an SSO device prompt also needs a person to complete it. For unattended runs, use identities that authenticate without interaction, and prefer exec or env to hand credentials to another process.

Arguments

*positionals

(Optional) Strings placed on the command line right after auth, in order: the subcommand and its positional arguments. Every value must be a string.

flags

(Optional) A dictionary of command-line options; see flag translation. A bare key such as "identity" becomes --identity, and registered shorthands resolve to their long form, so "i" resolves to --identity and "f" to --format for env. Other flags include --login for env, --format for list, and --all for logout.

args

(Optional) A list or tuple of strings appended after the flags. For exec, start the list with "--" followed by the command to run, such as args = ["--", "aws", "s3", "ls"].

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

Validate the authentication configuration

result = atmos.auth("validate", output = "capture", check = False)
if result.exit_code != 0:
    fail("The authentication configuration is invalid:\n" + result.stderr)
ui.success("The authentication configuration is valid.")

List identities as data

listing = atmos.auth("list", flags = {"format": "json"}, output = "capture")
identities = json.decode(listing.stdout)
print(identities)

Log in, then run a command under the identity

atmos.auth("login", flags = {"identity": "prod"})
atmos.auth("exec", flags = {"identity": "prod"}, args = ["--", "aws", "s3", "ls"])

The second call runs atmos auth exec --identity=prod -- aws s3 ls.

Pass temporary credentials to another call

credentials = atmos.auth("env", flags = {"format": "json", "identity": "prod", "login": True}, output = "capture")
atmos.terraform("plan", "vpc", "dev", env = json.decode(credentials.stdout))

The json format returns the environment variables as an object of string values, which env accepts directly. Use output = "capture" so the credentials are returned to the script and not shown on the terminal.

Related

• atmos.run runs any Atmos command from an argument list.
• atmos auth documents every subcommand and flag.
• Atmos Automation Language and the script step