Make a command work on another computer

A document-preview tool runs in one terminal but another computer reports that the command cannot be found. An absolute path fixes that error, yet the tool still cannot find its configuration. These failures occur at different stages: the shell locates a program, then the program locates its inputs. Treating both as a vague environment problem makes diagnosis harder.

The teaching case is a tool that reads a document list and produces a preview. A reproducible run needs an explicit starting directory, runtime, configuration, and network destination. All paths in the example are synthetic; the example does not inspect the computer's files.

How a command name selects a program

A shell parses the command line, processes quoting and expansions, and determines what to execute. A command can resolve to an alias, function, builtin, or executable file. For an external command that requires searching, PATH supplies directories in search order. Adding a directory to PATH does not change the working directory or install the program's dependencies.

Two directories can contain tools with the same name. The selected tool depends on shell resolution rules and PATH order; some shells also cache executable locations. Record the resolved program and its version, rather than only the short name typed at the prompt. In Bash, type -a tool can show resolution candidates. Consult the relevant documentation for another shell.

Relative paths start at the working directory. ./bin/tool refers to a file below that directory, whereas /project/bin/tool is an absolute teaching path. An absolute path is unambiguous locally but may not exist on another machine. Project instructions usually establish the repository root and then use paths relative to it.

Check the directory, quoting, and environment separately

Launching the same program from different directories can select different configuration files. State the starting directory, configuration argument, input path, and output location. Quote paths containing spaces according to the chosen shell. Bash single quotes generally preserve literal text, while double quotes still permit some expansion. A Bash script is not automatically a PowerShell script.

A process receives an environment when it starts. A shell variable is not necessarily exported to child processes, and changes in a child do not update its parent. An editor terminal, a program launched from a desktop icon, and a login terminal can receive different startup settings. When only one launch method works, compare its actual environment and arguments.

The preview tool might use READER_CONFIG and READER_PORT. Prefer project-specific variable names and avoid changing system variables such as HOME. A missing required value should produce an explicit failure rather than silently select production settings. Log presence, safe paths, and versions where useful. Do not dump credentials or the complete environment into diagnostic output.

Locate localhost and the listener

Localhost normally refers to loopback in the current network context. A browser on the host and a tool inside a container may use localhost to refer to different places. Matching port numbers do not establish that they reach the same process. Identify the client, host, container, and proxy before inspecting port mappings.

Binding to 127.0.0.1 generally accepts connections on the corresponding loopback interface. Binding to 0.0.0.0 listens on all IPv4 interfaces; reachability still depends on firewalls, container mappings, and networking. Clients should use a reachable server address rather than treat the wildcard binding address as their destination. Check private content and authentication before exposing a preview service.

A port conflict means a bind attempt failed. Inspect the listener and its launch source before stopping a process you own or choosing another port. Killing an arbitrary process can interrupt unrelated work and does not fix an incorrect binding address.

Observe PATH order with an offline model

The set below represents two executable files in an imaginary filesystem. The function searches candidate directories in order and continues past missing entries. It models only part of external-command lookup. It does not implement aliases, builtins, permissions, shell caching, or execution.

executables = {"/project/bin/tool", "/usr/bin/tool"}
def resolve(name, paths):
    for directory in paths:
        candidate = directory + "/" + name
        if candidate in executables:
            return candidate
    return None
assert resolve("tool", ["/project/bin", "/usr/bin"]) == "/project/bin/tool"
assert resolve("tool", ["/usr/bin", "/project/bin"]) == "/usr/bin/tool"
assert resolve("missing", ["/usr/bin"]) is None
print(resolve("tool", ["/project/bin", "/usr/bin"]))

The output is /project/bin/tool. Reversing the directory order changes the selected file, while an unknown name returns None. The assertions establish these model behaviors. They do not show that a real tool exists or has executable permission.

Successful lookup is also separate from successful startup. An interpreter, shared library, configuration file, or input may still be missing. Preserve the result of each stage before investigating the next one.

Write a reproducible run procedure

Use a disposable working directory. Confirm the operating system, shell, and runtime version, then check the dependency lockfile. Enter the documented project root, set the minimum required non-sensitive variables, and run the tool with synthetic input. Record each command, exit status, and expected file or response. The absence of error-colored text is not an acceptance condition.

A script should declare its interpreter and define failure handling. In Bash, do not assume every failed command in a pipeline becomes the pipeline's final status; select explicit checks and pipeline behavior for the script's needs. Execute unfamiliar setup steps separately so a failure has a clear location.

After startup, verify the listener, client request, and preview content separately. A running process does not establish that it read the intended input. Use placeholders for machine-specific paths in shared instructions and exclude real account details and credentials.

Exercise: reproduce three distinct failures

Write a run checklist containing the starting directory, runtime, configuration path, listener address, port, and expected output. Reproduce a missing PATH entry, an incorrect working directory, and an occupied port. Change one condition at a time and record the observation, diagnosis, and repair.

A reviewer should identify command resolution, file lookup, or network binding as the failed stage and obtain the same synthetic preview after repair. Also test a path containing spaces and a missing required variable. The path must arrive as one argument; the missing variable must produce a clear failure without starting the service.