watch

runbooks watch

Use runbooks watch to “watch” a runbook.mdx file (or its scripts, checks, or template files) for changes and automatically reload the Runbook as needed.

This command is intended for authors of runbooks.

Caution

When you update a command property, local template, or local script, the runbook will automatically load these changes in the UI, but because of the executable registry, the runbook will continue to execute the old versions of these files. The solution is to always restart your runbook (re-run runbooks watch) when you make a template or script change.

Usage

runbooks watch RUNBOOK_SOURCE [flags]

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.

Note

When watching a remote runbook, file watching operates on the local downloaded copy. Changes to the remote repository will not be detected automatically.

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.
• --disable-live-file-reload - Enable executable registry validation. Scripts will not reload from disk when they are updated; instead, you must re-run the runbooks command to apply script changes. This trades lower convenience for higher security. See Execution Security Model for details.
• --no-telemetry - Disable anonymous telemetry. Can also be set via RUNBOOKS_TELEMETRY_DISABLE=1 environment variable.

What it does

When you run runbooks watch:

1. Starts the Backend Server - Launches a Go-based HTTP server on port 7825
2. Opens Your Browser - Automatically navigates to http://localhost:7825
3. Watches for Changes - Monitors the runbook file for any modifications
4. Auto-Reloads - Automatically refreshes the browser when changes are detected (within ~300ms)

Writing a new runbook

runbooks watch /path/to/runbook

Then in your editor:

1. Make changes to runbook.mdx
2. Save the file
3. See your changes instantly in the browser - no manual refresh needed!

Technical details

File watching

• Uses fsnotify for efficient file system monitoring
• Watches the directory containing your runbook file
• Implements debouncing (300ms) to handle editors that save files multiple times
• Only triggers on Write and Create events for your specific runbook file

Auto-reload mechanism

• Uses Server-Sent Events (SSE) to push notifications from server to browser
• The browser maintains a persistent connection to /api/watch/sse
• When the file changes, the server sends a file-change event
• The browser receives the event and automatically reloads the page