Watch mode

Watch mode reloads the runbook in the app each time you save runbook.mdx. It is meant for runbook authors.

Caution

Each reload rebuilds the executable registry from the files on disk, so after a reload the app executes the current version of your commands and scripts. Pass --disable-live-file-reload to keep executing the versions that were present when the runbook was opened in this app session (opening another runbook and coming back rebuilds the registry).

Only changes to runbook.mdx itself trigger a reload. After you change a script that a <Command> or <Check> block runs from a file, the block shows a “Script changed” notice with the diff and keeps executing the version it loaded. Click Reload script in the notice to execute the new version, or save runbook.mdx, even unchanged: the reload rebuilds the registry and those blocks re-read their scripts, so each block shows the script it will execute. With --disable-live-file-reload, an unchanged save keeps the registry, so reload each changed script from its block. After you change a template or another file the runbook uses, change something in runbook.mdx, or close and reopen the runbook, to load it.

Activating watch mode

Pass --watch when you launch the app from the command line:

runbooks open --watch RUNBOOK_SOURCE

Then edit runbook.mdx in your editor and save it. The app shows the change about 300ms later.

Watch mode stays on for every runbook you open until you quit the app.

--watch and --disable-live-file-reload are read only when they start the app. If Runbooks is already running, a second runbooks command opens the runbook in the existing window with that window’s modes, whatever flags it passes. To change modes, quit Runbooks first.

Arguments

RUNBOOK_SOURCE is a local path or remote URL that points to a runbook.mdx file or to the directory that contains one. See runbooks open for the remote URL formats.

Note

For a remote runbook, Runbooks watches the local copy it downloaded. It does not detect changes to the remote repository.

Flags

--disable-live-file-reload keeps the executable registry that was built when the runbook was opened in this app session. Opening another runbook and coming back rebuilds it. Reloads still update what the app shows, but Runbooks keeps executing the original commands and scripts, and blocks whose script has changed show a “Script changed” warning. A block that runs a script file offers to reload that script from the warning.

Technical details

File watching

• Runbooks watches the directory that contains your runbook file with chokidar, so it still sees editors that save by replacing the file.
• It does not watch subdirectories, such as cloned repositories or generated output.
• It reacts only to write and create events for the runbook file. Changes to other files in the directory are ignored.
• It waits 300ms after the last event, so an editor that saves a file several times triggers one reload.
• Script files that blocks run are watched separately, with or without --watch. A change to one never reloads the runbook: its block shows the “Script changed” notice.

Reloading

• When the file changes, the main process sends a watch:file-change IPC event to the renderer.
• The renderer reloads the runbook, which re-reads the file and rebuilds the executable registry unless --disable-live-file-reload is set.
• A reload keeps the session. Environment variables that blocks exported, and the directory a block moved to with cd, stay as they were. Re-opening the runbook starts its blocks from the runbook’s directory again.