watch

runbooks watch

This command is intended for authors of Runbooks.

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.

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 <path-to-runbook> [flags]

Arguments

• <path-to-runbook> - Path to a directory containing the runbook.mdx file, or to the file itself.

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
• --working-dir-tmp - Use a temporary working directory (automatically cleaned up on exit)
  • Useful for isolated testing or sandboxed execution
  • Overrides --working-dir if both are specified
• --output-path <path> - Directory where generated files will be written (default: generated)
  • Resolved relative to the working directory
• --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