Loading

CLI reference docs from CLI Schema

docs-builder can generate a complete CLI reference section from a CLI Schema JSON file — the open, language-agnostic specification for machine-readable CLI descriptions. Describe your CLI once, and docs-builder generates navigable reference pages with usage synopses, parameter tables, and examples directly from the schema.

CLI Schema is an open standard (CC0 licensed) for describing command-line interfaces in a structured, machine-readable format. Think of it as OpenAPI, but for CLIs. A single schema file can power:

  • Reference documentation — generated by docs-builder
  • Shell completions — bash, zsh, fish, PowerShell
  • AI agent tooling — structured enough for LLMs to reason about your CLI
  • Validation — JSON Schema meta-schema included

  1. Generate a schema file

    Add a mechanism to your CLI that outputs a valid CLI Schema JSON document. The schema describes your CLI's structure: commands, namespaces, flags, arguments, types, and descriptions.

    The recommended approach is implementing the __schema meta-command convention — a built-in subcommand that outputs the schema to stdout:

    my-tool __schema > docs/cli-schema.json

    For CLIs built with frameworks that don't support __schema natively, write a build script that produces an equivalent JSON file conforming to the spec.

    Commit the schema file. It is the source of truth for the generated reference.

    Tip

    Add a CI step that regenerates the schema and fails if the checked-in copy has drifted:

    - name: Check CLI schema is up to date
  run: |
    my-tool __schema > docs/cli-schema.json.tmp
    diff docs/cli-schema.json docs/cli-schema.json.tmp || \
      (echo "cli-schema.json is out of date — regenerate and commit it" && exit 1)
    rm docs/cli-schema.json.tmp

  2. Add a cli: entry to docset.yml

    In your docset.yml, add a cli: entry to the toc: section pointing at the schema file:

    toc:
  - cli: cli-schema.json

    That's the minimal setup. docs-builder generates a navigation subtree and a page for every namespace and command in the schema.

    To give the section a stable URL prefix and a home for supplemental docs, also set folder::

    toc:
  - cli: cli-schema.json
    folder: cli-reference

    Use title: and navigation_title: to customize the generated root page:

    toc:
  - cli: cli-schema.json
    folder: cli-reference
    title: Elastic CLI reference
    navigation_title: CLI reference

    Use children: to prepend hand-written pages — installation guides, conceptual overviews, or quick-start tutorials — before the auto-generated reference:

    toc:
  - cli: cli-schema.json
    folder: cli-reference
    children:
      - file: installation.md
      - file: getting-started.md

  3. Write supplemental content for namespaces and commands

    Drop a supplemental file into the folder for any namespace or command page where you want to add context, usage examples, or richer parameter descriptions. The generated parameter table and usage synopsis are always present — supplemental files let you add to them.

    See Writing supplemental content for file naming conventions and heading rules.

  4. Done

    Your CLI reference section is live. As your CLI evolves, regenerate the schema and commit — the docs update automatically on the next build.

    Navigation indicators — generated pages show a ns (purple) or cmd (amber) badge in the sidebar, making it easy to distinguish schema-generated pages from hand-written ones.

Note

Maintaining docs-builder itself: after changing CLI options in src/tooling/docs-builder/Commands/, regenerate this repository's schema with:

dotnet run --project src/tooling/docs-builder -- __schema > docs/cli-schema.json

See CONTRIBUTING.md for the full workflow.

docset.yml key Description
cli: <path> Path to the CLI Schema JSON, relative to docset.yml
folder: <path> Supplemental docs folder; also sets the URL prefix
title: <title> Optional generated CLI root page title
navigation_title: <title> Optional generated CLI root navigation label
children: Regular toc items prepended before generated pages