= CLI Interface Contract :toc: :toclevels: 3 This document describes the CLI interface contract that the MCP server depends on. These contracts are verified by the CLI contract tests to ensure the MCP server continues to work as expected when the CLI changes. The MCP server wraps the `npx doc-tools` CLI to provide a natural language interface to Claude Code. The CLI must maintain specific commands, flags, and output formats for the MCP server to function correctly. == Command structure All commands follow the pattern: [,bash] ---- npx doc-tools [subcommand] [flags] ---- == Top-level commands === generate Generate various types of documentation. [,bash] ---- npx doc-tools generate [flags] ---- Subcommands are documented in the <> section. === get-redpanda-version Get the latest Redpanda version information. [,bash] ---- npx doc-tools get-redpanda-version [--beta] ---- *Output format:* [,bash] ---- REDPANDA_VERSION=v25.3.1 REDPANDA_DOCKER_TAG=docker.redpanda.com/redpandadata/redpanda:v25.3.1 REDPANDA_RELEASE_NOTES=https://github.com/redpanda-data/redpanda/releases/tag/v25.3.1 ---- *Flags:* --beta:: Get the latest beta/RC version instead of stable (optional) === get-console-version Get the latest Redpanda Console version information. [,bash] ---- npx doc-tools get-console-version ---- *Output format:* [,bash] ---- CONSOLE_VERSION=v2.7.2 CONSOLE_DOCKER_TAG=docker.redpanda.com/redpandadata/console:v2.7.2 CONSOLE_RELEASE_NOTES=https://github.com/redpanda-data/console/releases/tag/v2.7.2 ---- === --version Display the doc-tools version. [,bash] ---- npx doc-tools --version ---- *Output format:* [,bash] ---- .. ---- Example: `1.2.3` == Generate subcommands === property-docs Generate Redpanda configuration property documentation. [,bash] ---- npx doc-tools generate property-docs --tag [options] ---- *Required flags:* --tag:: Redpanda version to generate docs for (for example, `v25.3.1`, `25.3.1`, or `latest`) *Optional flags:* --generate-partials:: Generate AsciiDoc partials in addition to JSON --cloud-support:: Include cloud support information --overrides:: Path to property overrides JSON file *Output:* Creates one or more of: * `modules/reference/partials/properties.json` * `modules/reference/partials/cluster-properties.adoc` (with `--generate-partials`) * `modules/reference/partials/broker-properties.adoc` (with `--generate-partials`) * `modules/reference/partials/tunable-properties.adoc` (with `--generate-partials`) * `modules/reference/partials/topic-properties.adoc` (with `--generate-partials`) === metrics-docs Generate Redpanda metrics documentation. [,bash] ---- npx doc-tools generate metrics-docs --tag ---- *Required flags:* --tag:: Redpanda version to generate docs for *Output:* Creates `modules/reference/pages/public-metrics-reference.adoc` === rpk-docs Generate RPK command-line documentation. [,bash] ---- npx doc-tools generate rpk-docs --tag ---- *Required flags:* --tag:: Redpanda version to generate docs for *Output:* Creates AsciiDoc files in `autogenerated/v/rpk/` === rpcn-connector-docs Generate Redpanda Connect connector documentation. [,bash] ---- npx doc-tools generate rpcn-connector-docs [options] ---- *Optional flags:* --fetch-connectors:: Fetch connector definitions from Redpanda Connect repository --draft-missing:: Create draft pages for missing connectors --update-whats-new:: Update the what's new page --include-bloblang:: Include Bloblang documentation --data-dir:: Directory containing connector data --old-data:: Path to previous connector data for comparison --csv:: Export connector data as CSV --overrides:: Path to overrides JSON file *Output:* Creates component documentation files in `modules/reference/pages/redpanda-connect/components/` === helm-spec Generate Helm chart specification documentation. [,bash] ---- npx doc-tools generate helm-spec [options] ---- *Optional flags:* --chart-dir:: Path to Helm chart directory --tag:: Helm chart version --readme:: Include README content --output-dir:: Output directory for generated files --output-suffix:: Suffix for output files === cloud-regions Generate cloud regions documentation. [,bash] ---- npx doc-tools generate cloud-regions [options] ---- *Optional flags:* --output:: Output file path --format:: Output format (json, yaml, adoc) --owner:: GitHub repository owner --repo:: GitHub repository name --path:: Path to regions file in repository --ref:: Git reference (branch, tag, commit) --template:: AsciiDoc template file --dry-run:: Show what would be generated without writing files === crd-spec Generate Custom Resource Definition (CRD) specification documentation. [,bash] ---- npx doc-tools generate crd-spec --tag [options] npx doc-tools generate crd-spec --branch [options] ---- *Required flags (one of):* --tag:: Redpanda Operator version tag (for released content) --branch:: Branch name (for in-progress content) *Optional flags:* --source-path:: Path to CRD source files --depth:: Maximum depth for nested properties --templates-dir:: Directory containing documentation templates --output:: Output directory === bundle-openapi Bundle OpenAPI specifications. [,bash] ---- npx doc-tools generate bundle-openapi --tag [options] ---- *Required flags:* --tag:: Redpanda version for API specifications *Optional flags:* --repo:: Repository to fetch from --surface:: API surface to bundle (admin, connect, or both) --out-admin:: Output path for admin API bundle --out-connect:: Output path for connect API bundle --admin-major:: Major version for admin API --use-admin-major-version:: Use major version in admin API bundle --quiet:: Suppress output messages == Output format contracts === Version commands Version commands (`get-redpanda-version`, `get-console-version`) must output key-value pairs in the format: [,bash] ---- KEY=value ---- Lines starting with `#` are treated as comments and ignored by the MCP server. === Generate commands Generate commands should: * Write to stdout for informational messages * Write to stderr for errors * Exit with code 0 on success * Exit with non-zero code on failure The MCP server parses stdout to extract: * File counts (for example, "Generated 342 properties") * File paths created * Success/failure status == Error handling contracts === Missing required parameters Commands must exit with non-zero status when required parameters are missing. Example: [,bash] ---- $ npx doc-tools generate property-docs Error: Required flag --tag is missing $ echo $? 1 ---- === Invalid flags Commands must exit with non-zero status when invalid flags are provided. Example: [,bash] ---- $ npx doc-tools generate property-docs --invalid-flag-xyz Error: Unknown flag: --invalid-flag-xyz $ echo $? 1 ---- === Nonexistent commands The CLI must exit with non-zero status when nonexistent commands are called. Example: [,bash] ---- $ npx doc-tools generate nonexistent-command Error: Unknown command: nonexistent-command $ echo $? 1 ---- === Network errors Network errors (for example, GitHub API failures) are acceptable for version commands, but: * Must write error message to stderr * Must exit with non-zero status * Error message should indicate the network issue == Version compatibility The CLI must support the `--version` flag to output the current version. Format: `..` This allows the MCP server to verify compatibility and provide helpful error messages if the CLI version is incompatible. == Stability guarantees The MCP server depends on these CLI contracts remaining stable: *Command names and subcommands* must not change without a major version bump. *Required flags* must not be removed or renamed without a major version bump. *Output formats* for version commands must remain parseable. *Exit codes* must follow Unix conventions (0 = success, non-zero = failure). *Optional flags* may be added without breaking the MCP server. *New subcommands* may be added without breaking the MCP server. == Testing The `cli-contract.test.js` test suite verifies these contracts automatically. All tests must pass before releasing a new version of doc-tools that could affect the MCP server. Test categories: * Command structure - Verifies commands and subcommands exist * Flag support - Verifies required and optional flags are present * Output format - Verifies output can be parsed correctly * Error handling - Verifies proper exit codes and error messages * Version compatibility - Verifies version information is available == Breaking changes If a breaking change to the CLI is necessary: . Update the CLI with the breaking change . Increment the major version in package.json . Update the MCP server to handle both old and new interfaces (if possible) . Update the CLI contract tests to verify the new interface . Update this document with the new contract