Skip to main content

Toolchain now installs aws-cli, Node, and other multi-file tools correctly

· 3 min read
Brian Ojeda
Brian Ojeda
Contributor

You pinned aws/aws-cli in your toolchain, ran atmos toolchain install, and saw a green checkmark — then aws --version died with Failed to load Python shared library. Or you pinned nodejs/node and the install never finished at all, warning about "unknown type" and a file it couldn't find. The tools were right there in the registry, aqua installed them fine, but Atmos couldn't.

That's fixed. Multi-file tools now install completely and actually run.

The Problem​

Atmos installed tools by copying just the entrypoints named in the registry's files: list out of the downloaded archive — and throwing the rest away. That works for a single self-contained binary like jq or terraform. It breaks for "onedir" bundles that ship a binary plus the files it needs at runtime:

  • aws/aws-cli bundles its own Python runtime. Atmos kept aws and aws_completer and dropped the ~8,600 supporting files, including libpython. The install reported success, but the binary was dead on arrival (#2743).
  • nodejs/node exposes npm, npx, and corepack as symlinks into a sibling lib/ tree, and publishes under a v-prefixed path. Atmos skipped the symlinks as an "unknown type" and looked for node-24.18.0-... instead of node-v24.18.0-..., so the install failed outright (#2744).

The Fix​

Atmos now mirrors how the upstream aqua CLI installs these packages:

  • Preserves the whole archive for multi-file tools under a .pkg directory — so every executable stays next to the runtime files it needs — and records each entrypoint's real path in a small sidecar manifest, without creating any symlinks of its own (a design choice used consistently across Atmos).
  • Keeps the archive's own symlink entrypoints (like npm → ../lib/node_modules/...) instead of dropping them.
  • Resolves versions consistently, so a pinned 24.18.0 correctly finds the v24.18.0 archive that actually downloads.
  • Fails honestly: a broken or incomplete extraction no longer reports success or leaves an orphaned binary behind.

Single-binary tools are completely unaffected — they keep the exact same flat layout as before.

How to Use It​

Nothing new to learn. Pin the tools and install:

atmos toolchain install aws/aws-cli@2.35.15
atmos toolchain install nodejs/node@24.18.0
$ aws --version
aws-cli/2.35.15 Python/3.14.5 Linux/... exe/x86_64
$ node --version
v24.18.0
$ npm --version
11.16.0

See How tools are installed on disk for details on the layout.

Get Involved​

Toolchain is an experimental feature and we're actively hardening it. If a tool doesn't install cleanly, please open an issue with the owner/repo and version — those reports are exactly what drove this fix.