Skip to main content

atmos.version

The atmos.version function runs atmos version through the current Atmos executable. Use it to read the running Atmos version, list and inspect releases, install or uninstall Atmos versions, and manage version tracks from automation.

Usage​

atmos.version(
    *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 bare call atmos.version() runs atmos version, which shows the running version. The call atmos.version("show", "v1.194.0") runs atmos version show v1.194.0.

SubcommandPurpose
listList Atmos releases.
showShow details for a specific Atmos release.
installInstall a specific version of Atmos.
uninstallUninstall a specific version of Atmos.
trackManage tracked external versions with the Atmos Version Tracker. Also available as tracks.

The track subcommand has its own subcommands, such as status, lock, update, apply, verify, diff, list, show, get, add, set, and remove. Pass them after "track", as in atmos.version("track", "verify").

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

Arguments​

*positionals

(Optional) Strings placed on the command line right after version, in order: the subcommand and its positional arguments, such as a release version for show or install. Every value must be a string.

flags

(Optional) A dictionary of command-line options; see flag translation. A bare key such as "format" becomes --format, and registered shorthands such as "c" resolve to --check. Common keys are "format" and "check" for the bare command, and "limit", "offset", "since", "include-prereleases", and "installed" for list.

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​

Read the running version as data​

result = atmos.version(flags = {"format": "json"}, output = "capture")
info = json.decode(result.stdout)
ui.info("Running Atmos " + info["version"] + " on " + info["os"] + "/" + info["arch"])

List recent releases​

releases = atmos.version("list", flags = {"limit": 5, "format": "json"}, output = "capture")
print(json.decode(releases.stdout))

This runs atmos version list --limit=5 --format=json.

Verify version tracks in a pipeline​

result = atmos.version("track", "verify", output = "capture", check = False)
if result.exit_code != 0:
    fail("Version tracks are not locked, current, and applied:\n" + result.stderr)

Install a specific Atmos version​

atmos.version("install", "1.194.0")

Notes​

note

The list and show subcommands, and the "check" key in flags, contact GitHub, so they need network access. The "check" key becomes the --check flag of atmos version and is separate from the check keyword argument, which controls whether a nonzero exit code raises an error.

Related​