Specify the kbagent command-line interface and release it as 1.0.0 #791

Summary

kbagent has no specification for its command-line interface. Each command sets its own conventions for names, arguments, input, target selection, output, confirmation and exit codes. Users and AI agents cannot predict this behavior. This issue asks for one specification of the interface and for shared code and CI checks that enforce it. The unified interface then ships as kbagent 1.0.0. After that, every change to the command-line interface must follow the specification.

Proposal, version 3 of 2026-10-14: kbagent Interface Proposal (Keboola members only).

Evidence

The numbers come from main at c0bbecc (0.99.0), which has 289 commands. Method: a script walks the Typer command tree. The command categories come from OPERATION_REGISTRY. No command was run.

• Target selection. --project is required on 172 commands, optional on 36, repeatable on 20 and absent on 61. An omitted --project has different meanings. 18 read commands read all registered projects. Commands that require the option fail. Other commands use the default-project order.
• "All projects" has two forms: --all-projects (only sync pull, sync push and sync diff) and an omitted --project.
• Branch. --branch has 45 different help texts.
• IDs are given in three ways. 19 commands take positional arguments. The agent commands accept the same task ID as a positional argument, as --id and as --task-id.
• Input from a file has 12 option names.
• Short forms. -p works on 24 of the 228 commands that have --project.
• Safety flags. 24 of the 41 destructive commands have no --dry-run, and 8 have neither --yes nor --force. The 8 --force options have different meanings.
• Drift continues. A prototype of the CI check finds 611 violations (586 at 0.95.0). The 8 commands that were added after 0.95.0 brought 25 new violations. One of these pull requests was reviewed by hand against the draft rules.

Cause

Each of the bugs #684, #745 and #766 was fixed by one shared mechanism and a test that fails when code bypasses it:

• kbagent: kai / docs / component ignore the "project use" default project #684: one default-project order.
• Commands report success and exit 0 even when per-item operations fail #745: the helper item_failure_exit_code() (fix(cli): partial failures set the exit code and the headline (CLI-6) #747).
• 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 resolver effective_branch.resolve_branch() (fix(branch): report the branch each command uses, from one place (#766) #800).

A written rule alone does not hold. CONTRIBUTING.md asks for --dry-run and --yes on destructive commands, but 24 of the 41 destructive commands have no --dry-run. So the specification is the index of the shared mechanisms and the record of decisions, and checks enforce its rules.

Deliverables

1. docs/cli-interface-spec.md, at most about 5,000 words. Each rule has an ID, a level and one example. Each MUST rule names the CI rule, the contract test or the review step that enforces it. Areas:

   • command structure and naming
   • arguments and options
   • input
   • target selection: project, branch, stack, saved choices, all projects, environment variables, order of precedence
   • output: human output, the --json envelope, stdout and stderr, warnings
   • errors and exit codes
   • safety: --dry-run, --yes, --force, behavior without a terminal
   • repeatability
   • lists
   • help text
   • secrets
   • documents for agents: kbagent context and the plugin documents
   • long-running operations: --wait and --timeout
   • environment variables and global options
   • versions and updates
   • kbagent serve: how REST routes map to commands, and their HTTP methods
   • change policy and versioning

2. Shared code that new commands use: option definitions in one module, one command class for every command, the resolvers, the exit-code helper, one confirmation helper, and shared renderers for human output.

3. make cli-spec-check, with these parts:

   • rules that read the command tree and the source code
   • a baseline file with the existing violations and a blocking flag for each rule
   • offline contract tests for rules about runtime behavior

   CI fails on a new violation, on a baseline entry that is already fixed, and on a baseline that grows in a pull request.

4. Checks for human output: a rule that forbids direct printing in commands/ outside OutputFormatter and the shared renderers, and snapshot tests of the human output of each renderer.

5. docs/cli-manifest.json: a manifest that is generated from the command tree and committed. It contains the commands, options, value kinds, categories and help texts. The command reference, the command part of kbagent context, the check and the inventory report use it as their source.

6. A binding rule: CLAUDE.md, CONTRIBUTING.md and the kbagent-pr-reviewer playbook refer to the specification. The reviewer playbook checks the human-output rules and the manifest and snapshot diffs.

Release as 1.0.0

• The unified interface ships as kbagent 1.0.0. Tags keep the v prefix.

• New installs get 1.0 on the release day on every channel. This includes CI pipelines that install kbagent without a pinned version.

• Existing installs that update through kbagent stay on 0.x for 28 days after the published_at time of the GitHub release v1.0.0. Then they update themselves. kbagent reads this date from GitHub. The date is not in the code. kbagent update --major updates earlier.

• At least 14 days before 1.0.0, a 0.x patch release adds these parts to the updater:

  • a major-version gate (today the updater installs any newer version)
  • the migration date
  • a deprecation notice, on stderr and in warnings[] with --json
  • kbagent update --major

• The release workflow publishes v1.0.0 with make_latest: false until the migration date. Clients without the patch follow the "latest" flag.

• docs/migrate-to-1.0.md lists every change in 1.0.0.

• Until 1.0.0, the 0.x releases contain only these changes:

  • bug fixes, security fixes and fixes against data loss
  • the updater patch
  • additive forms for the migration (--all-projects, warnings[])

  All other interface changes ship in 1.0.0.

Change policy after 1.0.0

A deprecated form keeps working with a warning for at least 28 days. After that, a minor release removes it. A fix that restores documented behavior ships at once. The SDK follows semantic versioning.

Sub-issues

Each group of changes gets its own sub-issue under this issue. There is one list for the 0.x releases and one for 1.0.0. The proposal contains both lists.

Acceptance criteria

• docs/cli-interface-spec.md covers every area above and has an approved review.
• make cli-spec-check runs in CI with its baseline and fails on a new violation.
• docs/cli-manifest.json is committed, and CI checks that it is current.
• The rule against direct printing and the snapshot tests of the renderers run in CI.
• CLAUDE.md, CONTRIBUTING.md and the kbagent-pr-reviewer playbook refer to the specification as binding.
• One sub-issue exists for each group of changes, for the 0.x releases and for 1.0.0.
• The 0.x updater patch is released at least 14 days before 1.0.0, and 1.0.0 is released as described above.