Specify the complete kbagent command-line interface

[soustruh]

Summary

kbagent has no specification for its command-line interface. Each command sets its own conventions, for example for names, arguments, input, target selection, output, confirmation and exit codes. Users and AI agents cannot predict this behavior. This issue asks for one complete specification of the interface and a CI check that enforces its rules. Every change to the command-line interface must then follow the specification.

The specification covers the whole interface. The evidence below shows examples from several areas. It is not a complete list of the problems.

Evidence

The numbers below come from main at 2342bba, which has 281 commands. Method: a script walks the Typer command tree and reads the arguments and options of each command. The command categories come from OPERATION_REGISTRY. No command was run.

• Target selection. --project has four shapes, also among read-only commands: required (164 commands), optional (36), repeatable (20), and absent (61). An omitted --project has different meanings. Read commands run on all projects. Write commands that require --project fail without it. resolve_project_alias implements a default-project order (the flag, KBAGENT_PROJECT, the project use pin, the only registered project). Its docstring tells write commands to use it, but only 6 call sites do.
• "All projects" has two forms: --all-projects (only sync pull, sync push and sync diff) and an omitted --project (other read commands).
• Branch. --branch has at least 12 different help texts with different defaults: the active branch, production, the value default, or "ignores the active branch". 67 of the 144 write and destructive commands have --branch. Some commands without it still apply the branch use pin, for example workspace create (see branch use: active branch persists silently across sessions and is never echoed on config read/write, so config update can target a dev branch unnoticed #766).
• IDs are passed in three ways. 19 commands take positional arguments, for example stream delete SOURCE_ID, while data-app delete takes --app-id. The agent commands accept the same task ID as a positional argument, as --id and as --task-id.
• Input from a file has at least 11 option names: --file, --from-file, --configuration-file, --op-file, --secrets-file, --members-file, --sql-file, --value-file, --description-file, --public-key-file and --git-pat-file. Some options also accept @file or - inside the value, and other commands use --stdin.
• Short forms. -p works on 24 of the 220 commands that have --project.
• Safety flags. CONTRIBUTING.md says "Destructive operations have --dry-run and --yes flags". 24 of the 41 destructive commands have no --dry-run, and 8 have neither --yes nor --force. Only 22 of the 103 write commands have --dry-run. --force has different meanings: it skips a confirmation on some commands (stream delete) and overrides a safety check on others (storage delete-table, sync pull).
• Earlier fixes changed one command at a time: kbagent: kai / docs / component ignore the "project use" default project #684 (the default project was ignored by kai, docs and component), branch use: active branch persists silently across sessions and is never echoed on config read/write, so config update can target a dev branch unnoticed #766 (the branch pin applied without notice), Commands report success and exit 0 even when per-item operations fail #745 (success and exit 0 after a partial failure).

Why a specification and not more point fixes

A point fix corrects one command and leaves the others unchanged. A new command copies the command that its author used as an example. A written rule set with a CI check stops new drift. It also makes the remaining fixes a finite list.

Deliverables

1. docs/cli-interface-spec.md, which covers the whole command-line interface, with at least these areas:
   • Command structure and naming: groups, command names, verbs and nouns, and aliases.
   • Arguments and options: positional arguments versus options, option names, short forms, value types and formats (IDs, lists, times, sizes), and repeatable options.
   • Input: inline values, files, standard input, and JSON or YAML content, with one form for each.
   • Target selection: project, branch and stack. This includes defaults, the project use and branch use pins, "all projects", environment variables and the order of precedence.
   • Output: human output, the --json envelope and its field names, stdout versus stderr, warnings and progress. Every command that reads or writes a project or a branch reports the resolved project and branch, also in --dry-run.
   • Errors and exit codes: error codes, message content, exit codes and partial failure (see Commands report success and exit 0 even when per-item operations fail #745).
   • Safety: which command categories need --dry-run, --yes or an interactive confirmation, what --dry-run shows, what --force means, and the behavior without a terminal.
   • Repeatability: which commands are safe to run again, and how retries and idempotency keys work.
   • Lists: limits, pagination, sorting and filters.
   • Help text: the required content and style of --help.
   • kbagent serve: how REST routes map to commands, and which rules apply to them.
   • Change policy: how a breaking change is announced and deprecated, and how long an old form keeps working.
2. An inventory of all current commands against the specification: which commands comply, which need a change, and which changes are breaking.
3. A CI check (for example make cli-spec-check) that reads the command tree and fails on a new violation. A baseline file lists the existing violations, in the same way as scripts/file_size_baseline.json.
4. A binding rule: CLAUDE.md (Coding Conventions), CONTRIBUTING.md ("Checklist: Adding a New CLI Command") and the kbagent-pr-reviewer playbook refer to the specification. Every change to the command-line interface, by a person or an agent, must follow it.

Not in this issue

This issue does not change command behavior. After the specification is accepted, each group of required changes gets its own sub-issue under this one.

Breaking changes

Some rules will change current behavior, for example the meaning of an omitted --project or the name of an option. The specification must list each breaking change with its deprecation path. An early start costs less, because each new command that ships before the specification adds to the migration list.

Acceptance criteria

• docs/cli-interface-spec.md exists, covers every area in deliverable 1, and has an approved review.
• The inventory lists every command with its current and target behavior.
• make cli-spec-check runs in CI and fails on a new command that breaks a rule.
• CLAUDE.md, CONTRIBUTING.md and the kbagent-pr-reviewer playbook refer to the specification as binding.
• One sub-issue exists for each group of required changes.

[soustruh]

Input for the naming rules and the target selection area of this specification.

kbagent project use and kbagent branch use save the same kind of choice. The CLI names this choice differently for projects and for branches:

	Project (project use)	Branch (branch use)
Field in config.json	default_project	active_branch_id
CLI help and output	Pin <alias> as the default project, Pinned:	set the active branch, Branch ID to activate
--json	project current: "source": "pin", key pinned	none
REST (kbagent serve)	Get the active project, Switch the active project	Pin the active branch
Code	resolve_pinned_alias()	resolve_branch(), result effective_branch_id

• The project side uses three terms for one concept: "default project", "pin" and "active project".
• The branch side uses "active branch" and, in one REST summary, "pin".
• "Default" has two meanings. For a project, it is the saved choice. For a branch, it is the production branch, for example in Reset to the default branch.

The specification must select one term for this concept and use it for projects and branches in the CLI, in --json and in REST.

The fix for #766 does not change these names. It uses the current branch term, for example branch_source: "active_branch" in the --json output.

[linear-code]

CLI-20

[soustruh]

Linear: CLI-20