commands-reference.md7.0 KB

Toolchain Commands Reference

Complete reference for all atmos toolchain subcommands, flags, and usage patterns.

Persistent Flags (All Commands)

Flag	Env Var	Default	Description
`--github-token`	`ATMOS_GITHUB_TOKEN`, `GITHUB_TOKEN`	--	GitHub authentication token (hidden)
`--tool-versions`	`ATMOS_TOOL_VERSIONS`	`.tool-versions`	Path to .tool-versions file
`--toolchain-path`	`ATMOS_TOOLCHAIN_PATH`	XDG data dir, `.tools` fallback	Tool installation directory

atmos toolchain install

Install tools from .tool-versions or by name.

Prefer declarative dependencies.tools for normal Atmos execution. Use this command for manual bootstrap, cache warming, shell setup, ad-hoc verification, or tools outside a component/workflow/ custom-command execution context.

atmos toolchain install [tool@version] [flags]

Examples

atmos toolchain install                        # Warm/install .tool-versions for a shell or cache
atmos toolchain install terraform@1.9.8        # Ad-hoc install a specific version
atmos toolchain install jq                     # Bootstrap a repo-wide default tool

atmos toolchain update

Update one or more tools to their newest available version. If no tools are given, every tool in .tool-versions is updated.

A tool pinned to latest is re-resolved to the newest version. A tool pinned to an exact version is replaced with the newest available version and reinstalled. Tools pinned to pr:/sha:/ref: are skipped — those pins are immutable by design; use add to change them explicitly.

atmos toolchain update [tool...] [flags]

Flags

Flag	Env Var	Default	Description
`--dry-run`	`ATMOS_TOOLCHAIN_UPDATE_DRY_RUN`	false	Report what would change without installing anything
`--max-concurrency`	`ATMOS_TOOLCHAIN_MAX_CONCURRENCY`	4	Maximum number of tools to update concurrently

Examples

atmos toolchain update                              # Update every tool in .tool-versions
atmos toolchain update terraform                    # Update a single tool
atmos toolchain update terraform kubectl --dry-run  # Preview updates without installing

atmos toolchain uninstall

Remove an installed tool.

atmos toolchain uninstall <tool@version>

atmos toolchain add

Add a tool to the .tool-versions file.

atmos toolchain add <tool[@version]>...

If no version is specified, the latest available version is used.

Examples

atmos toolchain add terraform                  # Add latest version
atmos toolchain add terraform@1.9.8            # Add specific version
atmos toolchain add terraform kubectl helm     # Add multiple tools

atmos toolchain remove

Remove a tool from the .tool-versions file.

atmos toolchain remove <tool[@version]>

atmos toolchain set

Set the default version for a tool when multiple versions are installed.

atmos toolchain set <tool> <version>

atmos toolchain get

Get the version of a tool from the .tool-versions file.

atmos toolchain get [tool]

atmos toolchain list

Show installed tools with version, size, and installation date.

atmos toolchain list

atmos toolchain info

Display tool configuration from the registry.

atmos toolchain info <tool>

Shows: package type, source, supported platforms, available versions.

atmos toolchain which

Show the full filesystem path to a tool binary.

atmos toolchain which <tool>

atmos toolchain search

Search for tools across all configured registries.

atmos toolchain search <query>

atmos toolchain aliases

List all configured tool aliases.

atmos toolchain aliases

atmos toolchain exec

Execute a tool with a specific version, installing it first if needed.

atmos toolchain exec <tool@version> [-- args...]

Examples

atmos toolchain exec terraform@1.9.8 -- plan
atmos toolchain exec jq@1.7.1 -- '.foo' file.json

atmos toolchain env

Output PATH environment variables for shell evaluation.

atmos toolchain env [--format=bash|json|fish|powershell|github] [--relative]

Flags

Flag	Default	Description
`--format`	`bash`	Output format (bash, json, fish, powershell, github)
`--relative`	false	Use relative paths instead of absolute

Examples

eval "$(atmos toolchain env)"                         # Bash/Zsh
eval "$(atmos toolchain env --format=bash)"           # Explicit bash
atmos toolchain env --format=fish | source            # Fish
atmos toolchain env --format=powershell | Invoke-Expression  # PowerShell
atmos toolchain env --format=github                   # GitHub Actions; appends to $GITHUB_PATH when set

atmos toolchain path

Print PATH entries for installed tools (one per line).

atmos toolchain path

atmos toolchain du

Show disk usage of installed tools and cache.

atmos toolchain du

atmos toolchain clean

Remove all installed tools and cached registry data.

atmos toolchain clean

atmos toolchain registry list

List configured registries or tools in a specific registry.

atmos toolchain registry list [name]

Examples

atmos toolchain registry list              # List all registries
atmos toolchain registry list aqua         # List tools in aqua registry

atmos toolchain registry search

Search for tools across all configured registries.

atmos toolchain registry search <query>

Registry Configuration Reference

Aqua Registry

registries:
  - name: aqua
    type: aqua
    source: https://github.com/aquaproj/aqua-registry/tree/main/pkgs
    ref: v4.260.0           # Optional: pin to specific registry version
    priority: 10

Source formats:

GitHub tree URL: https://github.com/owner/repo/tree/ref/path
File path: file://./registry.yaml (single file)
File directory: file://./pkgs/ (per-package structure)

Inline (Atmos) Registry

registries:
  - name: custom
    type: atmos
    priority: 150
    tools:
      owner/repo:
        type: github_release          # or http
        url: "asset_{{.Version}}_{{.OS}}_{{.Arch}}.tar.gz"
        format: tar.gz                # tar.gz, zip, gz, raw
        files:
          - name: binary-name
            src: path/in/archive

Supported Package Types

Type	Description
`github_release`	Download from GitHub release assets
`http`	Download from arbitrary HTTP URL

Supported Archive Formats

Format	Description
`tar.gz`	Gzip tarball
`zip`	ZIP archive
`gz`	Single gzip-compressed binary
`raw`	Uncompressed binary
`pkg`	macOS installer package