Skip to content
Gruntwork Runbooks

serve

runbooks serve

Section titled “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.

Usage

Section titled “Usage”
Terminal window
runbooks serve RUNBOOK_SOURCE [flags]

Arguments

Section titled “Arguments”
  • 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.

Flags

Section titled “Flags”
  • --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.
  • --no-telemetry - Disable anonymous telemetry. Can also be set via RUNBOOKS_TELEMETRY_DISABLE=1 environment variable.

What it does

Section titled “What it does”

When you run runbooks serve:

  1. Starts the Backend Server - Launches a Go-based HTTP server on port 7825
  2. Serves the API - Provides REST endpoints for the frontend to call
  3. Does NOT Open Browser - You must manually navigate to http://localhost:7825 or run the frontend separately

Development workflow

Section titled “Development workflow”

Here’s a typical development workflow:

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

  2. In another terminal, start the frontend:

    Terminal window
    cd web
    bun dev

  3. Open your browser to http://localhost:5173 (Vite’s port)

  4. Make changes to:

    • React code in /web/src - hot reloads automatically
    • Go code - restart the serve command
    • Runbook files - refresh the browser