What is PATH? (why your terminal says command not found)

What it actually is

PATH is an environment variable, same category as the ones covered in environment variables, except this one is set up by your operating system, not your app. It holds an ordered list of folder locations, separated by colons on Mac and Linux, semicolons on Windows. Every time you type a command name into a terminal, the shell doesn’t magically know where that program lives. It walks the folders in PATH, left to right, checking each one for a file with that exact name, and runs the first one it finds.

Think of it like a restaurant’s short list of suppliers, checked in a fixed order. Ask for “tomatoes” and staff check supplier one, then two, then three, using whichever has it first. If none of them stock tomatoes, you get told it’s not available, even though a tomato exists somewhere in town. PATH not containing a folder means your shell can’t see what’s in it, no matter how real and correctly installed the program is.

Why your AI just did this

When your agent installs a command-line tool globally, something like npm install -g @anthropic-ai/claude-code, a Python tool via pipx, or a Homebrew formula, the installer drops the actual program file into one specific bin folder. For that program to be runnable by just typing its name (claude, not the full file location), that folder has to already be listed in PATH.

If it isn’t, a careful agent edits your shell’s config file, ~/.zshrc on macOS (zsh is the default shell there since Catalina), or ~/.bashrc / ~/.bash_profile on Linux and older bash setups, adding a line like export PATH="$HOME/.npm-global/bin:$PATH". That line means: search this folder too, and check it before anything else. It’s doing this so the tool it just installed, and every tool you install the same way afterward, works from any folder without you typing the full path to the executable each time.

When you’ll run into it

• zsh: command not found: claude or bash: claude: command not found, right after an install that reported success
• On Windows, the equivalent is 'claude' is not recognized as an internal or external command
• The command works in the terminal tab where you just installed it, then “disappears” in a brand new tab or after a reboot, because the shell config got edited but the running session never reloaded it
• You use nvm to manage Node versions, switch versions, and a globally installed CLI vanishes, because npm’s global bin folder is scoped per Node version
• Two different terminal apps (say, the built-in Terminal versus VS Code’s integrated terminal) behave differently for the same command, because they can load different shell config files

What to check

• Run echo $PATH (Mac/Linux) or echo $env:Path (Windows PowerShell) and actually read the list, don’t just confirm it printed something
• Run which claude (Mac/Linux) or where claude (Windows) to see exactly which file, if any, would run, and its full location
• Confirm the folder the installer used is one of the entries from echo $PATH, not just present somewhere on disk
• Open a new terminal window or tab after any PATH edit; an already-open one will not pick up the change on its own
• If you use nvm, check whether the command was installed under the Node version currently active, switching versions can hide it

Say it like a dev

Instead of: “the command doesn’t exist” Say: “it’s not found on my PATH, is it actually installed, or just not visible to the shell?”

Instead of: “it broke, let’s reinstall it” Say: “did we just edit PATH? I might just need a fresh terminal window for it to take effect”

Instead of: “why does this work sometimes and not other times” Say: “could this be an nvm thing, does the global bin path change when I switch Node versions?”