A developer checks a project command and its file context in a Linux terminal before running it elsewhere

Editorial illustration.

“It works on my machine” gets laughed off in standups, yet when a script passes in your SSH session and fails at 2:00 AM inside cron, a systemd unit, or a CI runner, that sentence is actually your best diagnostic clue. Your interactive terminal quietly supplies a dozen invisible inputs: your user account, your current directory, a populated PATH, shell aliases, version-manager shims from ~/.zshrc, and an active .env or SSH agent.

When an automated runner executes the exact same command string, most of those assumptions vanish. Fixing it reliably means surfacing those hidden inputs and encoding them into the script or service definition, rather than throwing sudo or random flags at the error until it stops complaining.

Why “the same command” runs in two different worlds

Take a simple build command:

deploy-tool build --output dist

In your interactive shell, deploy-tool might resolve through ~/.nvm/versions/node/v22.x/bin or ~/.local/bin, your working directory is already /srv/my-app, and your user owns the dist/ folder.

In cron or a systemd service, the process often starts in / with /bin/sh, a stripped-down PATH like /usr/local/bin:/usr/bin:/bin, and a dedicated service user such as www-data or runner that has never loaded ~/.bashrc or ~/.zshrc. The command text is identical; the execution context is completely different.

Capture the real exit status and environment first

Before guessing what broke, capture both stdout and stderr along with the real exit code:

set -o pipefail
your-command 2>&1 | tee /tmp/command-check.log
status=${PIPESTATUS[0]}
printf 'exit_status=%s\n' "$status"
exit "$status"

Pay attention to PIPESTATUS[0] (in Bash) so tee does not mask a failing command with exit code 0. A wrapper that swallows errors makes a CI dashboard or cron log look green while the actual build or backup quietly failed.

Next, inspect who the process is running as and where it starts:

id
pwd
command -v node || echo "node not in PATH"
printf 'PATH=%s\n' "$PATH"

If node, dotnet, or python3 resolves in your terminal but returns “not found” in the job, check whether your interactive shell relies on nvm, fnm, pyenv, or asdf shims that are never sourced by non-interactive shells. Either call the binary by its explicit path or configure the runtime explicitly in your CI/service environment.

Check variables, shells, and filesystem boundaries

Missing environment variables are the next usual suspect. Avoid dumping the entire env output into logs where database passwords or API tokens could be exposed. Instead, log presence checks and fail fast with a clear message:

: "${PUBLIC_BASE_URL:?PUBLIC_BASE_URL is required}"
: "${DATABASE_URL:?DATABASE_URL is required}"

Watch out for shell dialects too. A script written with Bash arrays or [[ ... ]] conditionals will break if cron executes it under /bin/sh (which is dash on Debian/Ubuntu). Put #!/usr/bin/env bash at the top of Bash scripts, quote variable expansions containing paths ("$target_dir"), and test the script using the exact interpreter your runner uses.

When you hit a “Permission denied” error even though the file’s mode looks fine, inspect the entire directory chain and mount flags—not just ls -l on the final file:

namei -l /srv/app/output/report.json
findmnt -no TARGET,OPTIONS /srv/app

namei -l shows whether a parent directory is missing the execute (x) bit for the service user, while findmnt reveals if a container volume or systemd ProtectSystem=strict sandbox mounted the target path read-only (ro) or noexec.

Reproduce the clean context before you deploy

Once you suspect which assumption is missing, test the command in a stripped environment locally instead of pushing ten trial-and-error commits to CI:

env -i PATH=/usr/local/bin:/usr/bin:/bin HOME=/tmp /bin/sh -c 'cd /srv/app && ./scripts/build.sh'

Running with env -i strips away your personal shell variables and aliases immediately. Whatever breaks under env -i is an implicit dependency you need to make explicit.

Wrap the command so it carries its own context

The durable fix is never “remember to cd into /srv/app first.” Put the required context into a small wrapper script or directly into your systemd unit (WorkingDirectory=, EnvironmentFile=) or CI step:

#!/usr/bin/env bash
set -euo pipefail

script_dir="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
cd "$script_dir"

: "${PUBLIC_BASE_URL:?PUBLIC_BASE_URL is required}"
test -f package.json || { echo 'package.json is missing' >&2; exit 1; }

exec npm run build

Using exec replaces the wrapper process with npm run build so signals and exit codes pass straight back to the caller, while set -euo pipefail stops execution on unset variables or failed pipes.

A few shortcuts consistently create bigger headaches later:

  • Running a failing job as root instead of fixing directory ownership for the service user.
  • Printing a full .env file in CI logs to debug one missing key.
  • Hiding failures with || true so a scheduler stops sending alert emails.
  • Installing unpinned CLI tools during production runs when a preflight check should have caught the missing binary.

For related operational habits that keep small sites predictable, see:

The environment around a command is part of the program. Once you make its user, working directory, runtime path, and required variables explicit, the command stops depending on your terminal session—and your memory.

Sources