A deploy job runs `ssh build@host 'mytool --version'` and fails with `zsh: command not found: mytool`, yet logging into that same account interactively and typing the command works. The PATH entry is exported from ~/.zshrc. Why does the remote command miss it, and where does the export actually belong?

## What ssh actually starts There are two very different things people call "ssh-ing in". `ssh host` allocates a terminal and starts the user's shell as a **login shell**. zsh then reads `.zshenv`, `.zprofile`, `.zshrc` and `.zlogin` — everything. `ssh host 'mytool --version'` starts the user's shell with `-c 'mytool --version'`. No terminal is allocated, and the shell is not a login shell. zsh reads `/etc/zshenv` and `~/.zshenv`, then executes the command and exits. Nothing else is consulted. So the symptom — works when I log in, fails when the job runs it — is not mysterious at all. Two different shells read two different sets of files. ## Why .zshrc is skipped, and why that is right The `rc` file is the *interactive* configuration. Everything in it assumes a human: aliases you type, a prompt you look at, key bindings, completion, colour. A batch process has no use for any of it, and sourcing several hundred lines of it before every remote command would be pure cost. zsh's file split is what makes that separation possible; the mistake is putting environment in the interactive file. ## The fix Move the export: ```zsh # ~/.zshenv export PATH="$HOME/.local/bin:$PATH" ``` Everything a *process* needs goes here. Everything a *person* needs stays in `~/.zshrc`. Things that look like fixes but are not: - **Re-adding the export to `.zshrc`.** It was never read. - **`ssh host -t 'zsh -lic "mytool"'`.** Forcing a login-interactive shell does make the config load, but you have now made a deploy job depend on someone's interactive dotfiles, prompt and all. It is a workaround, not a fix, and it breaks the day a plugin prints something. - **Assuming ssh will pass your local environment.** It will not, beyond what `sshd` is explicitly configured to accept. The most robust option for automation is to not depend on dotfiles at all: have the job invoke an absolute path, or set the environment in the job definition. Dotfiles are a convenience for humans; a pipeline that breaks when someone edits their shell configuration is badly coupled. ## The discipline .zshenv demands Because `.zshenv` runs for *every* zsh — every script with a zsh shebang, every remote command, every subshell that re-execs the shell — it has rules. **It must be silent.** File-transfer tools run a non-interactive shell on the remote side and read its stdout as protocol data. A cheerful `echo "Welcome back"` in `.zshenv` corrupts that stream, and the failure surfaces as a baffling `scp`/`sftp`/`rsync` error that mentions nothing about your shell. If you must print, guard it: ```zsh if [[ -o interactive ]]; then echo "Welcome back, $USER" fi ``` `[[ -o interactive ]]` tests a shell option; `[[ -t 1 ]]` tests whether stdout is a terminal. Either is better than an unguarded print. **It must be fast.** Anything you put here is paid by every zsh process. A `$(...)` call forks; a network lookup can hang a script that had no reason to touch the network. **It must not assume a terminal.** No key bindings, no prompt, no completion setup, no anything that expects line editing to exist. **It must not assume it runs once.** Naively prepending to `PATH` in `.zshenv` grows the variable each time a nested zsh starts. Either make the append idempotent or set `PATH` absolutely rather than prepending. ## Verifying the diagnosis Ask the remote shell directly rather than reasoning about it: ```zsh ssh build@host 'echo $PATH; echo $ZSH_VERSION; echo $-' ``` That prints the `PATH` the job actually sees, confirms the remote shell really is zsh, and shows the option flags — no `i` among them means non-interactive. Compare with the same command run in your interactive session and the missing entry is obvious. ## The adjacent trap The same class of bug has a variant that `.zshenv` does *not* fix: a scheduled job or a service manager may not run zsh at all. If the thing starting your command uses `/bin/sh`, or execs the binary directly with no shell involved, then no zsh file of any kind is read and the environment has to come from the job's own definition. Check what actually starts the process before you edit dotfiles.