How to write a CLI error report another developer can rerun

A CLI error report should include the repro command, tool version, input shape, working directory assumption, actual output, expected output, and the smallest change that makes the error disappear.

The most common weak report is a screenshot or pasted stack trace with no command. That may show the failure, but it does not show how to reach it. Start with the command exactly as run, then remove private paths and secret values. Replace a real filename with a small fixture name if possible. If the command depends on being run from a project root, say that. If the command uses an environment variable, name the variable and describe the allowed shape without exposing the value.

Next, separate actual and expected output. Actual output should include the exit code, error text, and the first relevant warning before the failure. Expected output should name the result the reporter believed was correct: a file generated, a field parsed, a clean validation error, or a nonzero count. If the expectation comes from a previous version, write the version number or date when it worked.

Finally, include one narrowing observation. Maybe the command works without a flag, works with a smaller file, fails only on Windows, or fails only when the input contains a blank row. That observation often saves more time than a long theory about the cause.

Do not paste tokens, customer data, private paths, or full unrelated logs. A good report makes the failure rerunnable while keeping the sensitive parts abstracted.

How to write a CLI error report another developer can rerun

// COMMENTS

ON THIS PAGE