CLI Version Mismatch Debug Checklist

A CLI version mismatch debug checklist helps explain why the same command behaves differently across a laptop, CI runner, container, or production helper machine. The mismatch may be in the CLI itself, its runtime, its plugin set, or the shell that launches it.

Start by recording the exact command and where it was run. Include the current working directory, shell, branch or commit, and whether the command was launched through a package script, globally installed binary, local binary, alias, wrapper script, or editor task. Many version bugs come from running a different executable than expected.

Next, record the binary path and version. For Node tools, compare `which`, `where`, `npm exec`, `pnpm exec`, or `npx` behavior. For Python tools, compare virtual environment activation, `python -m` invocation, and package path. For compiled CLIs, check whether the binary came from a system package manager, project cache, or standalone download.

Then compare plugin and config loading. A CLI may load plugins from the current project, the user home directory, a global install location, or an environment variable. Two machines can report the same main version while loading different plugins. Record config file paths and whether user-level config was disabled during the test.

After that, check lockfile and cache state. A project may have a lockfile that pins one version while a global binary calls another. CI caches may preserve an older CLI. Containers may install from a stale base image. If clearing cache fixes the issue, the note should still record which cache was responsible.

Finally, create one clean repro command. It should force the intended binary path, runtime version, and config file. The goal is not to permanently rely on a long command, but to prove which version boundary caused the behavior. Once confirmed, move the fix into the project script, toolchain file, or setup documentation.

CLI Version Mismatch Debug Checklist

// COMMENTS

ON THIS PAGE