> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ubiquex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ubx runbook

> Generate a comprehensive operational runbook from .xcl files and apply history.

`ubx runbook` reads your XCL source files and recent apply history, then uses AI to generate a comprehensive operational runbook in Markdown or HTML. Subsequent runs with `--update` regenerate only changed sections.

## Usage

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
ubx runbook [flags]
```

## Flags

| Flag               | Description                                 |
| ------------------ | ------------------------------------------- |
| `--out <file>`     | Write output to this file (default: stdout) |
| `--format <fmt>`   | Output format: `markdown`, `html`           |
| `--section <name>` | Generate only a specific section            |
| `--update <file>`  | Diff-aware update of an existing runbook    |

## Requirements

Requires `UBX_AI_API_KEY` environment variable or `ai.api_key` in `workspace.xcl`.

## Examples

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
ubx runbook                         # generate and print to stdout
ubx runbook --out RUNBOOK.md        # write to file
ubx runbook --format html           # HTML output
ubx runbook --section connect       # only the "Connecting" section
ubx runbook --update RUNBOOK.md     # update existing runbook (diff-aware)
```

## Sections

| Section     | Content                                                  |
| ----------- | -------------------------------------------------------- |
| `resources` | All managed resources and their purpose                  |
| `connect`   | How to connect to databases, clusters, services          |
| `scaling`   | How to scale resources up/down                           |
| `recovery`  | Recovery procedures for common failure scenarios         |
| `alerts`    | Recommended alerting thresholds                          |
| `cost`      | Current estimated costs and optimisation recommendations |

## Diff-aware update

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
ubx runbook --update RUNBOOK.md
```

ubx computes a fingerprint from the current XCL source + history. If the fingerprint matches the one embedded in `RUNBOOK.md`, no regeneration is needed. If it doesn't match:

* Without `--section`: regenerates the entire runbook
* With `--section`: regenerates only that section and merges it into the existing file

Manually edited sections are preserved when merging.

## AI model

Uses `configPkg.DefaultAIModel` (`claude-haiku-4-5`). Override in workspace config.