Skip to main content
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

ubx runbook [flags]

​
Flags

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

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

SectionContent
resourcesAll managed resources and their purpose
connectHow to connect to databases, clusters, services
scalingHow to scale resources up/down
recoveryRecovery procedures for common failure scenarios
alertsRecommended alerting thresholds
costCurrent estimated costs and optimisation recommendations

​
Diff-aware update

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.