Commands can't find tools (PATH issues)

Solo's managed commands receive an effective launch environment assembled from shell capture and command-configured variables. On Unix-like systems, Solo captures the login-shell environment on demand and caches it for up to 10 minutes. On Windows, Solo uses the app's inherited environment instead of running a login shell.

If a command reports something like node: command not found or cargo: command not found, that is a useful clue, but it does not by itself prove that a Unix shell capture is stale.

Why this happens#

On Unix-like systems, Solo runs the login shell in interactive login mode and parses its exported environment. Differences can still come from:

• Version managers like nvm, rbenv, pyenv, and asdf that initialize lazily or through shell functions.
• Homebrew or another package manager changing PATH after Solo last captured it.
• Different selected shells, execution profiles, startup files, functions, aliases, or shims.
• Command-configured variables overriding the captured PATH.

Step 1: Refresh the shell environment#

The quickest fix is to refresh Solo's cached environment:

1. Open the command palette using your configured Open command palette shortcut (Cmd/Ctrl+K by default).
2. Choose Refresh shell environment.

On Unix-like systems, Solo re-runs interactive login initialization and refreshes the cache. On Windows, Solo does not perform login-shell capture; relaunch Solo after changing system or user environment variables. After refreshing or relaunching, restart the affected command — already-running commands keep the environment they started with.

Step 2: Check what Solo sees#

Use your configured New agent/terminal shortcut (Cmd/Ctrl+T by default), then choose Create new terminal tab.

In a macOS/Linux/WSL/Git Bash shell:

which node
echo "$PATH"

In PowerShell:

Get-Command node
$env:PATH -split [IO.Path]::PathSeparator

In Command Prompt:

where node
echo %PATH%

Run the corresponding commands in a regular terminal and compare the results. A PATH difference is one likely cause; also compare the selected shell or execution profile and whether the tool is provided by a function, alias, or shim.

If the tool works in Solo's terminal but not in a managed command, inspect that command's configured Environment, especially a PATH override. A command-configured PATH takes precedence over the captured PATH.

Step 3: Use an absolute path#

As a last resort, use the full path to the executable in your command. For example, in a POSIX-like shell:

# Instead of: npm run dev
# Use: /opt/homebrew/bin/node /opt/homebrew/bin/npm run dev
 
# Or find the path:
which npm

For lookup on Windows-native shells, use Get-Command npm in PowerShell or where npm in Command Prompt.

This bypasses PATH lookup for the executables you name explicitly. Child processes and other commands may still consult PATH. It's not elegant, but it works reliably.

Common scenarios#

Checking Solo's captured PATH#

For a POSIX-like shell:

echo "$PATH" | tr ':' '
'

For PowerShell:

$env:PATH -split [IO.Path]::PathSeparator

For Command Prompt:

echo %PATH%

The POSIX and PowerShell forms print one entry per line; Command Prompt prints the semicolon-separated PATH. This makes missing directories easy to spot.