Skip to main content

atmos.toolchain

The atmos.toolchain function runs atmos toolchain <command> [tool] through the current Atmos executable. Use it for explicit toolchain operations such as installing a tool or listing what is installed.

Usage​

atmos.toolchain(
    command,
    tool = "",
    flags = {},
    args = [],
    working_directory = ...,
    env = ...,
    output = "stream",
    check = True,
)

Subcommands​

The command argument takes a subcommand of atmos toolchain:

SubcommandPurpose
installInstall CLI binaries from the registry.
uninstallUninstall a tool or all tools.
listList configured tools and their installation status.
add, remove, setEdit the .tool-versions file.
get, info, which, pathInspect tools and their paths.
update, lockUpdate versions and refresh the lock file.
exec, env, clean, duRun a tool, export its PATH, and manage caches.

Arguments​

command
Required. The toolchain subcommand, such as "install", "uninstall", or "list".
tool

(Optional) The tool the command applies to, for example "jqlang/jq@1.7.1". It is placed right after the command.

flags

(Optional) A dictionary of command flags, translated the same way as for the command wrappers.

args
(Optional) A list or tuple of strings appended after the flags.
working_directory, env, output, check

(Optional) The same process options as atmos.run.

The command argument must be non-empty, and neither command nor tool may start with a dash.

Returns​

A result with stdout, stderr, and exit_code. See exec.run.

The call runs the toolchain command in a separate Atmos process, so it does not change the calling script's PATH. Use dependencies.tools when later calls in the script need the tool.

Examples​

Install a tool​

atmos.toolchain("install", "jqlang/jq@1.7.1")

List installed tools​

installed = atmos.toolchain("list", output = "capture")
print(installed.stdout)

Pass a flag​

atmos.toolchain("list", flags = {"format": "json"}, output = "capture")

Related​