---
title: CLI reference docs from CLI Schema
description: docs-builder can generate a complete CLI reference section from a CLI Schema JSON file — the open, language-agnostic specification for machine-readable...
url: https://docs-v3-preview.elastic.dev/docs-builder/data/cli-schema
products:
  - Elastic Docs Builder
---

# CLI reference docs from CLI Schema
docs-builder can generate a complete CLI reference section from a [CLI Schema](https://cli-schema.org) 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.

## What is CLI Schema?

[CLI Schema](https://cli-schema.org) 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


## Getting started

<stepper>
  <step title="Generate a schema file">
    Add a mechanism to your CLI that outputs a valid [CLI Schema](https://cli-schema.org) 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:
    ```bash
    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:
      ```yaml
      - 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
      ```
    </tip>
  </step>

  <step title="Add a cli: entry to docset.yml">
    In your `docset.yml`, add a `cli:` entry to the `toc:` section pointing at the schema file:
    ```yaml
    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:`:
    ```yaml
    toc:
      - cli: cli-schema.json
        folder: cli-reference
    ```
    Use `title:` and `navigation_title:` to customize the generated root page:
    ```yaml
    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:
    ```yaml
    toc:
      - cli: cli-schema.json
        folder: cli-reference
        children:
          - file: installation.md
          - file: getting-started.md
    ```
  </step>

  <step title="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](https://docs-v3-preview.elastic.dev/docs-builder/data/cli-schema/supplemental) for file naming conventions and heading rules.
  </step>

  <step title="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.
  </step>
</stepper>

<note>
  **Maintaining docs-builder itself:** after changing CLI options in `src/tooling/docs-builder/Commands/`, regenerate this repository's schema with:
  ```bash
  dotnet run --project src/tooling/docs-builder -- __schema > docs/cli-schema.json
  ```
  See [CONTRIBUTING.md](https://github.com/elastic/docs-builder/blob/main/CONTRIBUTING.md#cli-reference-maintenance) for the full workflow.
</note>


## Reference


| 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    |