serve

runbooks serve

Use runbooks serve to start the backend API server without starting the frontend server or opening the browser.

This command is intended for developers of the Runbooks tool itself.

runbooks serve RUNBOOK_SOURCE [flags]

RUNBOOK_SOURCE - A local path or remote URL pointing to a runbook.mdx file, the directory containing a runbook.mdx file, or an OpenTofu/Terraform module directory. See runbooks open for supported remote URL formats and OpenTofu/Terraform module auto-detection.

--working-dir <path> - Base directory for script execution and file generation (default: current directory)
- All relative paths are resolved from this directory
- Can be absolute or relative to current directory
- Use --working-dir=::tmp for a temporary directory (automatically cleaned up on exit), useful for isolated testing or sandboxed execution
--output-path <path> - Directory where generated files will be written (default: generated)
- Resolved relative to the working directory
--tf-runbook <keyword-or-path> - Select a built-in template or provide a local custom runbook for OpenTofu/Terraform modules. Remote URLs are not supported. See runbooks open for available templates and details.
--port <number> - Port for the backend server (default: 7825).
--no-telemetry - Disable anonymous telemetry. Can also be set via RUNBOOKS_TELEMETRY_DISABLE=1 environment variable.

When you run runbooks serve:

Starts the Backend Server - Launches a Go-based HTTP server on localhost (port 7825 by default, configurable with --port)
Serves the API - Provides REST endpoints for the frontend to call
Does NOT Open Browser - You must start the frontend dev server separately (see Development workflow below) and manually navigate to http://localhost:5173 (or other frontend server port)

Here’s a typical development workflow:

Start the backend:
Terminal window
```
runbooks serve testdata/demo-runbook
```
Or if you want to easily re-compile the backend:
Terminal window
```
go run main.go serve testdata/demo-runbook
```
In another terminal, start the frontend:
Terminal window
```
cd web
bun dev
```
Open your browser to http://localhost:5173 (Vite’s port)
Make changes to:
- React code in /web/src - hot reloads automatically
- Go code - restart the serve command
- Runbook files - refresh the browser