---
title: "CLI Documentation"
guide-section: "Site Content"
bread-crumbs: false
tags: [CLI, Content]
---

# CLI Documentation

If your Python package includes a command-line interface built with
[Click](https://click.palletsprojects.com/), Great Docs can generate reference pages for it
automatically. Each command and subcommand gets its own structured page showing the usage signature,
description, typed options, and examples, all using the same layout as API reference pages. This means
your CLI documentation stays perfectly in sync with your code, because everything is extracted
directly from Click at build time.

This page covers how to enable CLI documentation, how Great Docs discovers your commands, what the
generated pages look like, and how to write CLI help text that produces clear, useful reference
pages.

## Enabling CLI Documentation

Add the following to your `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
cli:
  enabled: true
```

With this single setting, Great Docs handles the rest: it finds your Click commands, captures their
help output, and generates reference pages during every build. No additional configuration is needed
for standard project layouts.

## How It Works

When CLI documentation is enabled, Great Docs runs a pipeline that mirrors how it handles API
documentation: discover, extract, generate, and integrate. Here's what happens during each build:

1. **Finds your CLI**: looks for Click commands in common locations
2. **Discovers entry point**: reads `[project.scripts]` from `pyproject.toml`
3. **Extracts metadata**: introspects each command for its description, options, arguments,
   subcommands, and examples
4. **Generates structured pages**: creates `.qmd` files in `reference/cli/` with the same layout
   as API reference pages
5. **Updates navigation**: adds a CLI section to the sidebar

The pipeline runs as part of `great-docs build`, so CLI pages are always regenerated from the
current state of your code. You never need to update them manually.

## Auto-Discovery

Most Click-based packages follow a handful of common patterns for where the CLI entry point lives.
Great Docs checks these locations automatically, so you rarely need to tell it where to look:

1. `your_package.cli`: the most common location
2. `your_package.__main__`: for `python -m your_package` support
3. `your_package.main`: alternative location
4. entry point module from `[project.scripts]`

Great Docs tries each location in order and uses the first one that contains a Click command.

### Entry Point Detection

If you have a `[project.scripts]` section:

```{.toml filename="pyproject.toml"}
[project.scripts]
my-cli = "my_package.cli:main"
```

Great Docs uses `my-cli` as the command name in documentation.

## Explicit Configuration

If your CLI lives in a non-standard location, or if auto-discovery picks up the wrong command
object, you can specify the module and command name explicitly in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
cli:
  enabled: true
  module: my_package.commands   # Module containing Click commands
  name: app                      # Name of the Click command object
```

The `module` value should be the dotted import path to the Python module containing your Click group
or command. The `name` value is the variable name of the Click command object within that module.
With explicit configuration, Great Docs skips auto-discovery entirely and goes straight to the
specified location.

## Generated Output

Once Great Docs discovers your CLI, it generates a set of reference pages that integrate into the
existing site navigation. Here's what to expect.

### Sidebar Structure

CLI commands appear in the Reference sidebar:

```
Reference
├── API
│   └── (your classes and functions)
└── CLI
    ├── my-cli (main command)
    ├── my-cli build
    ├── my-cli deploy
    └── my-cli config
```

### Page Format

Each CLI page uses the same structured layout as API reference pages, making the site feel cohesive.
A generated page contains these sections in order:

1. **Title** with a colored label badge (`cli` or `cli-group`)
2. **Subject**: the first paragraph of your docstring (the short description)
3. **Usage signature**: a `bash` code block showing the invocation pattern
4. **Extended description**: remaining paragraphs from your docstring, formatted as prose
5. **Collapsible `--help` output**: the full raw `--help` text, tucked inside a disclosure widget
6. **Arguments**: if the command takes positional arguments
7. **Options**: a definition list with name, type, default, and help text
8. **Subcommands**: for groups, each subcommand links to its own page
9. **Examples**: if your docstring includes an `Examples:` section

This structured layout gives readers quick access to what they need (usage, options, examples)
while preserving the full `--help` output for those who want the raw reference.

#### Text enhancements

Within the description and option help text, Great Docs automatically applies two enhancements:

- **Single-quoted text → code**: `'great-docs build'` in your docstring renders as
  `great-docs build` in inline code
- **Option names → code**: references to options like `--watch` or `--from-repo` are rendered as
  inline code automatically

These enhancements are applied automatically during page generation. You don't need to use
backticks or any special markup in your Click docstrings or `help=` strings.

## Writing Good CLI Help

The quality of your CLI documentation depends on the help text you write in your Click decorators
and docstrings. Great Docs parses your docstrings into structured sections, so following a few
conventions produces the best results.

### Use Descriptive Help Text

Every Click command should have a docstring that explains what it does. The first paragraph becomes
the **subject** (displayed prominently at the top of the page), and remaining paragraphs form the
**extended description**:

```{.python filename="cli.py"}
@click.command()
@click.argument("path")
@click.option("--output", "-o", help="Output directory for generated files")
@click.option("--verbose", "-v", is_flag=True, help="Enable verbose logging")
def build(path, output, verbose):
    """Build the project at PATH.

    This command compiles all source files and generates output
    in the specified directory. Use --verbose to see detailed
    progress information.
    """
    ...
```

The first paragraph is especially important because it also appears as the short description in
the parent group's **Commands** list and in search results.

### Document All Options

Every `@click.option()` should include a `help=` string. Options without help text appear in the
reference page but give readers no indication of what they do. Use single quotes around file names
or values to have them rendered as inline code:

```{.python filename="cli.py"}
@click.option(
    "--format",
    type=click.Choice(["json", "yaml", "toml"]),
    default="json",
    help="Output format (default: json)"
)
@click.option(
    "--config",
    help="Path to config file (default: 'pyproject.toml')"
)
```

In the generated page, `'pyproject.toml'` in the second option's help text becomes inline code
automatically, so the rendered description reads "Path to config file (default: `pyproject.toml`)".

### Use Click Groups for Subcommands

If your CLI has multiple commands, use a `@click.group()` to organize them. Great Docs generates a
separate page for each subcommand and links them together in the sidebar:

```{.python filename="cli.py"}
@click.group()
def cli():
    """My CLI application for managing projects."""
    pass

@cli.command()
def init():
    """Initialize a new project."""
    ...

@cli.command()
def build():
    """Build the project."""
    ...
```

Well-structured Click groups produce the clearest documentation. Each subcommand becomes its own
page, and the group's docstring serves as the overview for the CLI section.

### Include Examples

If your docstring contains a paragraph starting with `Examples:`, Great Docs extracts it into a
dedicated **Examples** section rendered as a `bash` code block. Use Click's `\b` marker to prevent
paragraph rewrapping:

```{.python filename="cli.py"}
@click.command()
def deploy():
    """Deploy the built site.

    Uploads the contents of _site/ to your configured host.

    \b
    Examples:
      my-cli deploy                  # Deploy to production
      my-cli deploy --dry-run        # Preview what would happen
      my-cli deploy --target staging # Deploy to staging
    """
    ...
```

Without the `\b` marker, Click joins continuation lines into a single paragraph, which would
collapse the example lines together. Always place `\b` on its own line before `Examples:` to
preserve the formatting.

## Example: Great Docs CLI

Great Docs uses this feature to document its own CLI. Here's what the generated page for
`great-docs build` looks like (simplified):

**Subject and usage:**

> Build your documentation site.

```bash
great-docs build [OPTIONS]
```

**Extended description (formatted as prose):**

> Requires `great-docs.yml` to exist (run `great-docs init` first). This is the only command you
> need day-to-day and in CI.

**Collapsible `--help` output:**

The full raw terminal output is available inside a disclosure widget labeled "Full --help output".
Readers can expand it when they want the complete reference, but it doesn't dominate the page.

**Options (structured definition list):**

| Option | Type | Description |
|--------|------|-------------|
| `--watch` | flag | Watch for changes and rebuild automatically |
| `--no-refresh` | flag | Skip re-discovering package exports |
| `--versions` | TEXT | Build only specific versions (comma-separated) |
| `--from-repo` | TEXT | Clone a remote Git repository and build its docs |

**Examples (bash code block):**

```bash
great-docs build                      # Full build with API refresh
great-docs build --no-refresh         # Fast rebuild (skip API discovery)
great-docs build --watch              # Rebuild on file changes
```

The main group page (`great-docs`) additionally includes a **Commands** section that links to each
subcommand's dedicated page. You can see these pages live in the Great Docs reference section.
All of these sections are generated from the same Click decorators and docstrings shown earlier
in this guide.

## Styling

CLI reference pages share the same visual system as API reference pages:

- **Colored label badges**: `cli` (blue) and `cli-group` (teal) distinguish commands from groups
- **Structured definition lists**: options are displayed with the same parameter styling used for
  function signatures in API docs
- **Consistent layout**: subject, signature, description, and parameters mirror the API page
  structure
- **Responsive design**: pages adapt to mobile and desktop viewports
- **Collapsible details**: the raw `--help` output is available but doesn't clutter the page

This shared design language means readers moving between API docs and CLI docs see the same
patterns: a short subject at the top, a signature block, extended prose, and a structured parameter
list.

## Troubleshooting

If CLI documentation isn't working as expected, here are the most common issues and how to resolve
them.

### CLI Not Detected

If your CLI isn't found:

1. verify Click is installed
2. check the module path is correct
3. ensure the Click command is importable
4. use explicit configuration:

```{.yaml filename="great-docs.yml"}
cli:
  enabled: true
  module: your_package.cli
  name: cli   # The Click command object name
```

If auto-discovery finds a Click command but it's the wrong one, explicit configuration lets you
point to the correct object directly.

### Help Text Missing

If commands show minimal help:

1. add docstrings to your Click functions
2. add `help=` to all options
3. use `@click.argument()` with proper names

The generated page will still show the command's usage signature and options, but the subject and
extended description sections will be empty without a docstring.

## Next Steps

CLI documentation works best when your Click commands already have good help text and docstrings.
Great Docs takes what you've written and turns it into browsable, searchable reference pages that
stay in sync with your code.

- [User Guides](user-guides.qmd) explains how to add narrative documentation
- [Deployment](deployment.qmd) covers publishing to GitHub Pages
