Migrating command-line syntax
Suppose your notes CLI used --from-stdin to read a note from a pipe. The new command accepts --body TEXT for a literal and --body - for piped text. Existing shell scripts still need to work, and their authors need to know what to change.
Declare the current body flag once. Register a plugin with transformArgv to expand the old switch into the two new tokens. The parser, stdin reader, and duplicate checks then see the same invocation as a user typing --body -. For a second spelling that takes exactly the same value, a flag alias is sufficient.
Try the migration
From a DreamCLI checkout, run the old and new commands with the same input:
$ printf 'Released\n' | bun examples/argv-transforms.ts add changelog --from-stdin
Use --body - in place of --from-stdin.
changelog: Released
$ printf 'Released\n' | bun examples/argv-transforms.ts add changelog --body -
changelog: Released
$ bun examples/argv-transforms.ts add --body 'Literal title' -- --from-stdin
--from-stdin: Literal titleThe first command writes the migration hint to stderr. Both piped commands write the same note to stdout, so a script that redirects the note keeps working. In the third command, -- ends option parsing and the title is literally --from-stdin.
Where each hook fits
- DreamCLI selects the command and handles built-in help. A
beforeParseobserver can inspect the original arguments for the selected command. Its return value is ignored. - DreamCLI awaits each registered
transformArgvin order. The notes plugin handles onlyadd, rewrites tokens before--, and returnsmetadata: { usedFromStdin: true }. Returning nothing leaves both arguments and metadata alone. - DreamCLI parses the final arguments. In the action,
parse.flag('body')reports--bodyfor either piped command. Readparse.metadata.usedFromStdinto decide whether to warn. Useflags.bodyfor the resolved note text.
When chaining plugins, give each plugin its own metadata key. A later transform can read earlier entries and replace a top-level key. Each invocation starts with an empty metadata object.
Test the CLI boundary
Register the plugin on your CLI and call app.execute(argv, { stdinData }). Run the legacy and current forms with the same input. Assert that both succeed and produce identical stdout, then check that only the legacy form emits the migration hint on stderr. Include a literal after -- to catch rewrites that accidentally change user data.