Mendapi 0.5.4: twelve fixes to the first minute of a CLI

Mendapi 0.5.4 is out on npm. It contains no new features. All twelve changes are things that annoyed people (mostly me) in the first minute of using the CLI.

I want to write this one down because "first-run polish" is the kind of work that never gets a blog post, and the list is a decent catalogue of the ways a Node CLI can be subtly wrong.

What mendapi does, briefly

It watches the OpenAPI specs and SDK feeds of APIs you depend on, works out which upstream changes actually touch your codebase (file and line), and drafts the fix as a diff you review. It runs offline by default, so your source never leaves the machine. npx mendapi scan in a repo is the whole onboarding.

The twelve

CLI conventions

• mendapi --version did not exist. It does now, and it reads from package.json rather than a hardcoded string, so it cannot drift.
• Subcommand --help exited with a usage-error code. That is correct for wrong usage and wrong for someone asking for help. It exits 0 now. This matters more than it sounds: CI wrappers and agent harnesses treat nonzero as failure.
• Help text went to stderr. So mendapi fix --help | grep apply printed nothing and looked broken. Moved to stdout.
• mendapi sync --help triggered a network fetch before printing usage. Asking a command what it does should never hit the network.

Output

• Every subcommand emitted the node:sqlite ExperimentalWarning on stderr. Harmless, ugly, and worse than ugly under MCP, where it polluted the stdio channel.
• mendapi scan on a large repo printed hundreds of impacts and blew past the scrollback. The terminal report now caps at 25 with an honest "N more not shown" line. --json and --out stay complete, because truncating machine-readable output would be a lie.

Environment and paths

• engines claimed a Node version we do not actually support. The real floor is 22.13, because node:sqlite is flagged below that. On older runtimes users got ERR_UNKNOWN_BUILTIN_MODULE, which tells you nothing. It now fails with a sentence you can act on.
• The change database resolved somewhere that did not survive reinstalls. It is ./.mendapi/sentinel.db now, with a MENDAPI_DB override.
• --out-dir had no sensible default. It is cwd/.mendapi.

MCP

• serverInfo.version was a literal, so the MCP server could report a version it was not. Read from package.json now.
• The MCP tool list was out of sync in three places (--help, the CLI summary, the README): revalidate was missing from all of them. If you were driving mendapi from an agent, that tool was invisible.

The one I found afterwards

While writing the regression gate for the help changes I noticed mendapi scan -h was not printing help at all. The CLI recognised -h, but passed it through to the scanner subprocess, whose arg parser only accepts ---prefixed flags. So -h was silently ignored and scan did a full walk of the current directory: 40 seconds, a 941KB report emitted where usage text should have been, exit 0 by luck. Fixed in the tree by normalising to --help before spawn; it ships in 0.5.5. If you are on 0.5.4, use --help rather than -h.

I mention it because it is a good example of a bug that hides behind a passing exit code. The test asserted exit 0 and got exit 0.

Try it

npx mendapi@0.5.4 --help
npx mendapi@0.5.4 scan

Zero npm dependencies, AGPL. Repo: https://github.com/mendapi/mendapi — release notes: https://github.com/mendapi/mendapi/releases/tag/v0.5.4 — docs: https://mendapi.com/docs/

If something in your first minute is worse than it should be, that is the kind of report I want.