What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Replacing a Commander import with burgee/commander does not make a command’s printed text into JSON data. In the example below, an action prints a human-readable line but returns no value, so [email protected] wraps the result as "data":null. To return useful JSON, make the handler return a serializable object and keep human-facing prose off stdout in machine mode.
Why the JSON envelope contains null
Commander action handlers are callbacks that receive declared command arguments, parsed options, and the command object. Commander’s documentation shows handlers writing output themselves; that is a valid pattern for an interactive CLI. But printing and returning are different operations: text sent with console.log does not become the handler’s return value.
As an Amazon Associate I earn from qualifying purchases.
In the maintainer’s example, which uses [email protected] and [email protected], the action prints a line and returns no object. The resulting JSON envelope has "data":null. The envelope exists, but the handler supplied no structured result for its data field. This is the behavior reported by Ofri Peretz, burgee’s maintainer; the example was not independently reproduced. Source: Ofri Peretz’s article.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsReturn data separately from display text
Make the action return a serializable value
Have the action return the value that a script or agent should consume. For example:
#1 Best Overall
const result = { file, lines: lines.length };
return result;The object is the machine-facing result. A line such as “Processed 12 lines” is presentation for a person, not a substitute for that object.
Keep prose off machine-readable stdout
When a JSON or MCP response is expected on stdout, incidental logs can make the stream unparsable. The maintainer’s article demonstrates the risk of a line appearing before an MCP JSON-RPC response; it does not establish that every client or invocation arrangement fails in the same way. Route human messages through one output helper or policy, and have it stay silent on stdout when the invocation is machine-oriented.
Rank #2
The article’s example detects --json or --mcp by searching process.argv. The author calls this check crude and notes that the cited 0.11.1 façade has no public machine-mode flag. Treat it as an example-specific workaround, not a guaranteed or current API:
const machineMode = process.argv.includes("--json") ||
process.argv.includes("--mcp");
function say(message) {
if (!machineMode) console.log(message);
}Centralizing output makes the policy easier to change if the invocation mechanism changes. Do not assume this argument check reliably identifies every way a command can be run.
What the import swap does—and does not—establish
Peretz reports replacing the Commander import with burgee/commander across seven invocations in the example. He says usage errors still exited with status 1. Those are release- and example-specific compatibility claims, not a guarantee that every Commander CLI behaves identically after the swap.
The article also reports two issues encountered while drafting against [email protected], both fixed in 0.11.1: MCP argument mapping for a declared hyphenated flag, and completion suggestions for negated flags. If either matters to your CLI, verify the relevant behavior against the exact version you plan to use rather than extrapolating from that report. Source: maintainer’s version report.
Rank #4
When the adapter may be worth adopting
The decision is not simply whether an import can be changed. It is whether the machine-facing interfaces are useful enough to justify the extra dependency and any handler changes.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →| Decision area | What the maintainer reports | What to check in your CLI |
|---|---|---|
| Existing commands and errors | Seven invocations were swapped in the example; usage errors still exited 1. | Exercise the commands, flags, help, and error cases your users rely on. |
| Machine interfaces | The product site positions burgee as projecting help, JSON, schema, MCP, and shell completions from one declaration. This is product positioning, not independent evaluation. | Confirm which interfaces your chosen version actually exposes and whether they fit your clients. |
| Handler results and stdout | The demonstrated JSON result is null when the action prints but returns no value; the article says an action throw remains uncaught under --json. |
Return structured values, keep machine output parseable, and decide how your application should handle thrown errors. |
| Runtime and TypeScript | The author reports the Node range changing from >=22.12.0 to ^20.19.0 || >=22.13.0 after Commander leaves dependencies. He says the swapped file ran on Node 20 and 22, excluding 22.12.x, and notes TypeScript’s legacy node resolver cannot see the subpath. |
Check the package’s version metadata and test your actual Node and TypeScript configuration. These are not statements of current support policy. |
| Package footprint | The author reports Commander 15.0.0 unpacked at 207,368 bytes, versus burgee 0.11.1 plus five sibling packages at 1,266,628 bytes; his bundle gate reads 1.514×. | Measure the effect in your own install and distribution setup; the reported figures are version-specific and not an independent benchmark. |
How to interpret the reported test result
Peretz reports that his run of Commander’s own suite produced 1360 / 1360 for both burgee/commander and a real Commander control. That comparison indicates how the adapter performed on the retained suite in that run; it does not test every additional interface introduced by the adapter. The counts are the maintainer’s reported result, not an independent measurement. Source: maintainer’s test and package comparison.
Quick Recap
A practical migration check
- Inventory output consumers. Find commands whose printed text is scraped by scripts or agents, and identify what structured value those consumers need. Peretz frames the key question this way: “Which command in your CLI prints something an agent currently scrapes with a regex, and what would returning it instead break?”
- Update one handler at a time. Return the data explicitly, then direct human-readable messages through a single output policy.
- Exercise machine and interactive paths. Check JSON, MCP if used, normal terminal output, usage errors, thrown errors, and any flags or completions important to your CLI.
- Validate the project environment. Confirm Node compatibility and whether your TypeScript module-resolution mode resolves the
burgee/commandersubpath.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
