CLI Failure Triage Note

CLI Failure Triage Note is a structured way to separate command syntax mistakes, environment configuration, dependency versions, permissions, and remote service failures.

The first field is the exact command. Copy the command as executed, including flags, working directory, relevant environment variables with secrets removed, and whether it was run in PowerShell, bash, zsh, CI, Docker, WSL, or a package script. Many CLI failures come from shell quoting, path separators, current directory, or missing flags rather than the tool itself.

The second field is version context. Record CLI version, runtime version, package manager version, lockfile state, operating system, and whether the command worked before an upgrade. If a plugin or extension is involved, include that version too. Without version context, a maintainer may test against a newer or older behavior and miss the failure.

The third field is error shape. Separate parse errors, validation errors, missing file errors, permission errors, network errors, authentication errors, and remote 5xx responses. The text after the first stack frame is often less useful than the first clear error message. Keep the full log locally when needed, but public reports should show the smallest useful excerpt.

The fourth field is isolation. Try the command with a smaller input, a fresh directory, a dry-run flag, a known-good config, or a direct API call. If the smaller case works, the failure may be project-specific. If the fresh case fails, the issue may be installation, auth, network, or a wider regression.

A good CLI triage note ends with one of three states: reproduced with minimal command, blocked by missing environment detail, or likely external service failure. That state tells the next person what action is possible without reading the whole thread.

CLI Failure Triage Note

// COMMENTS

ON THIS PAGE