open

runbooks open

Use runbooks open to open a runbook in the Runbooks desktop app.

Usage

runbooks open RUNBOOK_SOURCE [flags]

Arguments

• RUNBOOK_SOURCE - A local path or remote URL pointing to a runbook.mdx file or the directory containing a runbook.mdx file.

Local paths

runbooks open ./path/to/runbook
runbooks open /absolute/path/to/runbook
runbooks open ./path/to/runbook.mdx

Remote sources

You can open a runbook directly from a GitHub or GitLab URL without cloning the repo first:

# GitHub browser URL (copy/paste from your browser)
runbooks open https://github.com/org/repo/tree/main/runbooks/setup-vpc

# GitLab browser URL
runbooks open https://gitlab.com/org/repo/-/tree/main/runbooks/setup-vpc

# OpenTofu/Terraform module source format
runbooks open github.com/org/repo//runbooks/setup-vpc?ref=v1.0
runbooks open "git::https://github.com/org/repo.git//runbooks/setup-vpc?ref=main"

| Format | Example | |--------|---------| | GitHub browser (dir) | https://github.com/org/repo/tree/main/runbooks/setup-vpc | | GitHub browser (file) | https://github.com/org/repo/blob/main/runbooks/setup-vpc/runbook.mdx | | GitLab browser (dir) | https://gitlab.com/org/repo/-/tree/main/runbooks/setup-vpc | | GitLab browser (file) | https://gitlab.com/org/repo/-/blob/main/runbooks/setup-vpc/runbook.mdx | | OpenTofu GitHub shorthand | github.com/org/repo//path?ref=v1.0 | | OpenTofu git::https | git::https://github.com/org/repo.git//path?ref=main |

Note

When opening a remote runbook, a temporary working directory is automatically used (equivalent to --working-dir=::tmp). You can override this with --working-dir if needed.

Authentication for private repos

For public repositories, no authentication is needed. For private repositories, set one of the following:

• GitHub: GITHUB_TOKEN or GH_TOKEN environment variable, or run gh auth login
• GitLab: GITLAB_TOKEN environment variable, or run glab auth login

Flags

• --watch - Enable watch mode for live-reload during authoring.
• --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
• --no-telemetry - Disable anonymous telemetry. Can also be set via RUNBOOKS_TELEMETRY_DISABLE=1 environment variable.

What it does

When you run runbooks open:

1. Downloads (if remote) - If given a remote URL, downloads just the runbook directory via sparse git clone
2. Launches the app - Opens the Runbooks desktop window and loads the specified runbook
3. Renders the runbook - The app parses and renders the runbook.mdx file, providing an interactive UI for the runbook’s steps, scripts, and forms
4. Keeps running - The app continues running until you close the window

If the app is already running, a second invocation focuses the existing window and opens the new runbook in it.

Troubleshooting

Runbook not found: Make sure the path points to a valid runbook.mdx file or a directory containing one.

Authentication errors for remote runbooks: If you see “authentication required”, make sure you have set the appropriate token for the git host. See the Authentication section above.