# Commands can't find tools (PATH issues)

Solo's managed commands receive an effective launch environment assembled from [shell capture](../environment/shell-environment.md) 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](../environment/version-managers.md) 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](../command-palette/using.md) 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](../commands/start-stop-restart.md)** — 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](../command-palette/new-tab-picker.md)**.

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

```sh
which node
echo "$PATH"
```

In PowerShell:

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

In Command Prompt:

```bat
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:

```sh
# 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

| Symptom | Likely cause | Fix |
|---------|-------------|-----|
| `node: command not found` | Node version manager not initialized | Refresh env; make sure the manager initializes from your login shell |
| `python3: command not found` | Python version manager not initialized | Refresh env; verify the Python shim or virtualenv is on PATH |
| Homebrew-installed tool missing | Homebrew's bin directory is not in the effective PATH | Add `/opt/homebrew/bin` on Apple Silicon or `/usr/local/bin` on Intel macOS to your shell config, then refresh |
| `cargo: command not found` | Rust not installed or PATH stale | Refresh env; verify Rust install |
| `command not found` for all tools | Solo's PATH is completely empty | Check shell init files; manually refresh |

## Checking Solo's captured PATH

For a POSIX-like shell:

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

For PowerShell:

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

For Command Prompt:

```bat
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.

---

Are you a human? Read this doc on the web: https://soloterm.com/docs/troubleshooting/path-issues