# 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

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

## Subcommands

The `command` argument takes a subcommand of [`atmos toolchain`](/cli/commands/toolchain/usage):

| Subcommand | Purpose |
| --- | --- |
| [`install`](/cli/commands/toolchain/install) | Install CLI binaries from the registry. |
| [`uninstall`](/cli/commands/toolchain/uninstall) | Uninstall a tool or all tools. |
| [`list`](/cli/commands/toolchain/list) | List configured tools and their installation status. |
| [`add`](/cli/commands/toolchain/add), [`remove`](/cli/commands/toolchain/remove), [`set`](/cli/commands/toolchain/set) | Edit the `.tool-versions` file. |
| [`get`](/cli/commands/toolchain/get), [`info`](/cli/commands/toolchain/info), [`which`](/cli/commands/toolchain/which), [`path`](/cli/commands/toolchain/path) | Inspect tools and their paths. |
| [`update`](/cli/commands/toolchain/update), [`lock`](/cli/commands/toolchain/lock) | Update versions and refresh the lock file. |
| [`exec`](/cli/commands/toolchain/exec), [`env`](/cli/commands/toolchain/env), [`clean`](/cli/commands/toolchain/clean), [`du`](/cli/commands/toolchain/du) | Run 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](/functions/automation/atmos.run#flag-translation).
- **`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`](/functions/automation/atmos.run#arguments).

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`](/functions/automation/exec.run#returns).

The call runs the toolchain command in a separate Atmos process, so it does not change the calling script's `PATH`.
Use [`dependencies.tools`](/functions/automation/dependencies.tools) when later calls in the script need the tool.

## Examples

### Install a tool

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

### List installed tools

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

### Pass a flag

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

## Related

- [`dependencies.tools`](/functions/automation/dependencies.tools) installs tools and adds them to the script's `PATH`.
- [`atmos.run`](/functions/automation/atmos.run) runs any Atmos command from an argument list.
- [`atmos toolchain`](/cli/commands/toolchain/usage) documents every subcommand and flag.