CLI Change Checklist

Use this checklist whenever a change adds, removes, renames, or changes behavior for an sb command, option, argument, help string, default, or output contract.

Required updates

1. Update the command help at the Typer command definition.
2. Update user-facing docs that mention the command, flag, output, or workflow.

3. Regenerate the committed UI schema:

   sb ui-schema --write-default
   

4. Regenerate the auto-gen CLI reference (the published doc):

   make docs-reference
   

5. Run the schema + docs drift checks (both run on every PR in CI):

   sb ui-schema --check
   make docs-check
   

6. Check command-runner impact for commands that should be available in the web UI or Mac shell. The command runner reads /cli/schema, which is backed by brain/ui_schema/cli_schema.json.

7. Add or update tests near the behavior being changed. For schema-only drift:

   pytest -q tests/infra/test_cli_schema_sync.py
   

Recommended validation

Run the narrow command help first:

sb <command> --help

Then run the relevant feature tests. Before a release or broad CLI change:

sb dev review

Common failures

• sb ui-schema --check fails — regenerate brain/ui_schema/cli_schema.json with sb ui-schema --write-default, review the schema diff, rerun the affected UI or command-runner tests.
• make docs-check fails — docs/reference/cli.md drifted from the schema. Run make docs-reference to regenerate.