Skip to main content

atmos.config

The atmos.config function runs atmos config through the current Atmos executable. Use it to read values from the effective configuration, edit atmos.yaml by dot-notation path, and validate or format the file from automation.

Usage​

atmos.config(
    *positionals,
    flags = {},
    args = [],
    working_directory = ...,
    env = ...,
    output = "stream",
    check = True,
)

Get operations default to JSON and captured output. Read result.data for the typed value or result.stdout for raw JSON. Use flags = {"format": "raw"} for unquoted text and output = "stream" to display output live. Other operations retain streaming output. See query defaults.

Subcommands​

Pass the subcommand and any positional arguments as strings before the keyword arguments. The call atmos.config("get", "logs.level") runs atmos config get logs.level --format=json and captures its output.

SubcommandPurpose
getRead a value from the effective Atmos configuration by dot-notation path.
setSet a value in atmos.yaml by dot-notation path.
deleteDelete a value from atmos.yaml by dot-notation path. Also available as del and unset.
listList editable atmos.yaml setting paths.
formatFormat the active atmos.yaml file. Also available as fmt.
validateValidate atmos.yaml against its JSON Schema.
schemaPrint the atmos.yaml JSON Schema.

See the atmos config command reference for the complete list of subcommands and flags.

Arguments​

*positionals

(Optional) Strings placed on the command line right after config, in order: the subcommand and its positional arguments, such as the dot-notation path and the new value for set. Every value must be a string, so pass "true" or "5" rather than a boolean or an integer.

flags

(Optional) A dictionary of command-line options; see flag translation. For example, {"type": "int"} becomes --type=int for set.

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 data, stdout, stderr, and exit_code. See atmos.run for output and error behavior.

Examples​

Read a setting​

base = atmos.config("get", "base_path")
print("base_path is", base.data)

Set a typed value​

atmos.config("set", "logs.level", "debug")
atmos.config("set", "logs.exclude", '["a", "b"]', flags = {"type": "yaml"})

The second call runs atmos config set logs.exclude '["a", "b"]' --type=yaml, which stores the value as a YAML list.

Fail early on an invalid configuration​

validation = atmos.config("validate", output = "capture", check = False)
if validation.exit_code != 0:
    fail("atmos.yaml is invalid:\n" + validation.stderr)

Related​