Safe workflow for adding a new codex-multi-auth ... command without expanding scope or breaking the existing CLI contract. For the full dispatch contract and the two-registry trap, see RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md.
Add one new command path while keeping:
codex-multi-auth ...as the canonical command family- current help text and aliases aligned with docs
- JSON and human-readable output predictable
- command behavior covered by targeted tests
lib/codex-manager/commands/<name>.ts— command implementationlib/codex-manager.ts—CLI_COMMAND_HANDLERSregistrationlib/codex-manager/account-manager-commands.ts—ACCOUNT_MANAGER_COMMANDSregistration (required for the barecodex-multi-auth <name>form)lib/codex-manager/help.ts—printUsage()textdocs/reference/commands.mdREADME.mdwhen user-visible workflow changestest/codex-manager-cli.test.tstest/documentation.test.tsdocs/upgrade.mdwhen the command changes user-visible behavior or a documented workflowpackage.jsonscripts, when the command adds or changes a build/test entrypoint referenced by docs
- Add the command logic as a module under
lib/codex-manager/commands/, then register it in bothCLI_COMMAND_HANDLERSandACCOUNT_MANAGER_COMMANDS. - Keep usage text literal and copy-pasteable, and add the line to
printUsage()inlib/codex-manager/help.tsunder the section matching its role (Start here / Daily use / Repair / Diagnostics / Advanced). - Reuse existing storage, refresh, and quota helpers instead of adding new command-local state.
- Take collaborators as an injected
depsobject so the command stays testable. - Add or extend CLI tests in
test/codex-manager-cli.test.tsfor:- success path under both dispatch forms (
codex-multi-auth auth <name>and barecodex-multi-auth <name>) - invalid input or missing args
- JSON mode if supported
- non-interactive behavior if relevant
- success path under both dispatch forms (
- Update
docs/reference/commands.mdwith the command and flags. - Update
README.mdonly when the command changes the recommended user workflow. - Update
test/documentation.test.tsif new command text must stay aligned across docs and runtime usage text.
npm run lint
npm run typecheck
npm test -- test/codex-manager-cli.test.ts test/documentation.test.ts
npm run buildThen run the real command or its --help path once and inspect the output.
- command name is consistent across runtime and docs
- registered in both
CLI_COMMAND_HANDLERSandACCOUNT_MANAGER_COMMANDS(bare form works) - help text matches actual flags
- no unrelated settings or storage changes were mixed in
- JSON output is stable if exposed
- tests cover failure paths, not only the happy path