asdf: Fix Missing Shims with asdf reshim in CI
asdf only creates a shim for an executable that existed when you installed or last reshimmed, so after installing a new CLI you must run asdf reshim or it is "not found".
A frequent asdf-in-CI surprise is a freshly installed CLI being "command not found". asdf routes everything through shims, and a shim only exists if asdf knew about the binary; reshim regenerates them.
What it does
asdf places one shim per executable in $ASDF_DATA_DIR/shims (on PATH). When you install a global package that ships a binary (an npm -g install, a pip install, a gem), the binary lands inside the tool version but no shim points at it until asdf reshim scans for it.
Common usage
asdf install nodejs 20.11.1
npm install -g pnpm # new binary, but no shim yet
asdf reshim nodejs # generate the pnpm shim
pnpm -v # now resolves
asdf which node # show what a shim resolves toOptions
| Command / flag | What it does |
|---|---|
| asdf reshim | Regenerate shims for all plugins |
| asdf reshim <name> | Reshim a single plugin |
| asdf which <cmd> | Show the real path a shim points to |
| asdf where <name> | Print the install dir of the current version |
| ASDF_DATA_DIR | Override the data/shims directory |
| asdf exec <cmd> | Run a command bypassing shim lookup |
In CI
Add asdf reshim after any step that installs a tool-provided binary globally, or the next step cannot find it. Some plugins (nodejs, python) run reshim automatically on asdf install, but globally installed CLIs are not covered. Ensure $ASDF_DATA_DIR/shims stays on PATH across steps.
Common errors in CI
"<tool>: command not found" right after a global install is the classic missing-shim case; run asdf reshim. "No version is set for command <x>; please run asdf <tool> <version>" means the command exists but no version is selected in .tool-versions. asdf which <cmd> returning nothing confirms the shim was never generated.