open

runbooks open opens a runbook in the Runbooks desktop app.

Usage

runbooks open RUNBOOK_SOURCE [flags]

Arguments

RUNBOOK_SOURCE is a local path or remote URL that points to a runbook.mdx file or to the directory that contains one.

Local paths

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

Because open is the command name, write a folder that is named open as a path: runbooks open ./open.

Remote sources

You can open a runbook directly from a GitHub or GitLab repo, or from a repo on any other git host, without cloning it first. The source can point at the repo root, at a directory containing a runbook.mdx, or at a runbook file. The same sources work in the desktop app’s Open from URL dialog.

Browser URLs

Copy the URL from your browser’s address bar while viewing the runbook’s directory or its runbook.mdx:

runbooks open https://github.com/org/repo/tree/main/runbooks/setup-vpc
runbooks open https://github.com/org/repo/blob/main/runbooks/setup-vpc/runbook.mdx
runbooks open https://gitlab.com/group/subgroup/repo/-/tree/main/runbooks/setup-vpc

Format	Example
GitHub directory	https://github.com/org/repo/tree/main/runbooks/setup-vpc
GitHub file	https://github.com/org/repo/blob/main/runbooks/setup-vpc/runbook.mdx
GitLab directory	https://gitlab.com/group/repo/-/tree/main/runbooks/setup-vpc
GitLab file	https://gitlab.com/group/repo/-/blob/main/runbooks/setup-vpc/runbook.mdx
Repo root	https://github.com/org/repo

The branch, tag or commit in the URL is used. Branch names that contain slashes (release/v1) work. So do commit permalinks (/blob/<sha>/...) and query strings or anchors the browser adds, such as GitLab’s ?ref_type=heads. For github.com and gitlab.com, the https:// prefix is optional.

Directory and file URLs from GitHub Enterprise and self-hosted GitLab work too, and need the https:// prefix. A repo root URL on one of those hosts works only when Runbooks can tell which kind of host it is:

• A GitHub Enterprise Cloud host on ghe.com, or a GitHub Enterprise Server host you logged in to with gh auth login or named in GH_HOST.
• A GitLab host with gitlab as a dot- or hyphen-separated part of its name, such as gitlab.example.com or gitlab-ce.corp.net.

For a repo root on any other host, use a git:: source.

Git sources in go-getter syntax

Runbooks also accepts git sources written in go-getter syntax, the syntax of a Terragrunt source and of an OpenTofu or Terraform module source. A double slash (//) separates the repo from the path inside it. ?ref= picks a branch, tag or commit. Without ?ref=, Runbooks uses the repo’s default branch.

runbooks open github.com/org/repo//runbooks/setup-vpc?ref=v1.0
runbooks open github.com/org/repo//runbooks/setup-vpc/runbook.mdx
runbooks open gitlab.com/group/subgroup/repo//runbooks/setup-vpc?ref=main
runbooks open "git::https://git.example.com/org/repo.git//runbooks/setup-vpc?ref=main"
runbooks open "git@github.com:org/repo.git//runbooks/setup-vpc?ref=v1.0"

Format	Example
GitHub shorthand	github.com/org/repo//runbooks/setup-vpc?ref=v1.0
GitLab shorthand	gitlab.com/group/subgroup/repo//runbooks/setup-vpc?ref=v1.0
Any git host over HTTPS	git::https://git.example.com/org/repo.git//runbooks/setup-vpc?ref=main
SSH	git::ssh://git@github.com/org/repo.git//runbooks/setup-vpc or git@github.com:org/repo.git//runbooks/setup-vpc

As in go-getter, github.com/org/repo/runbooks/setup-vpc (without the //) also works, because a GitHub repo is always owner/repo. GitLab projects can sit under nested groups, so GitLab shorthand needs the // to mark where the path starts. Quote sources that contain ? or & so your shell leaves them alone.

Runbooks parses these sources itself and fetches them with git. It doesn’t use the go-getter library, so it differs from go-getter in a few places:

• Runbooks recognizes scheme-less shorthand for github.com and gitlab.com only. runbooks open reads any other scheme-less source, bitbucket.org/org/repo included, as a local path. For other hosts, use git::https://.
• git:: takes a full https://, http:// or ssh:// URL, or a git@host:path address. Runbooks rejects git::github.com/org/repo.
• Git over HTTPS, HTTP or SSH is the only way Runbooks fetches. go-getter’s other getters (s3::, gcs::, hg::) and archive URLs such as https://example.com/runbook.zip don’t work, and Runbooks rejects git::file://.
• ?ref= is the only query parameter Runbooks reads. It ignores depth, sshkey and any others.
• A + in ?ref= stays a + (?ref=v1.0.0+build.1), where go-getter reads it as a space.

Note

When you open a remote runbook, Runbooks clones the whole repository into a temporary directory, as go-getter does for a // subdirectory. The runbook’s folder inside that clone becomes the working directory: scripts start there, and generated files are saved inside it. Because the rest of the repository is there too, a runbook can use files outside its own folder, such as templates elsewhere in the repo. The temporary directory is deleted when you quit Runbooks.

Authentication for private repos

Public repositories need no authentication. For a private repository:

• On GitHub, set the GITHUB_TOKEN or GH_TOKEN environment variable, or run gh auth login.
• On GitLab, set the GITLAB_TOKEN environment variable, or run glab auth login.

A token in an environment variable is sent only to github.com or gitlab.com unless you name another host:

• For GitHub Enterprise Server, set GH_ENTERPRISE_TOKEN and GH_HOST=<host>, or run gh auth login --hostname <host>.
• For a GitHub Enterprise Cloud tenant on ghe.com, set GITHUB_TOKEN and GH_HOST=<host>.
• For self-hosted GitLab, set GITLAB_TOKEN and GITLAB_HOST=<host>, or run glab auth login --hostname <host>.

These tokens are used only for HTTPS sources. SSH sources (git@... or ssh://...) authenticate with your SSH keys, so the key must be loaded in your SSH agent and the host must already be in ~/.ssh/known_hosts.

Flags

Flag	Effect
--watch	Turns on watch mode, which reloads the runbook when you save it.
--no-telemetry	Turns off anonymous telemetry. Setting RUNBOOKS_TELEMETRY_DISABLE=1 does the same.
--verbose	Keeps the command attached to the terminal and prints the app’s logs there until you quit Runbooks. Use it to troubleshoot a launch that shows no window. It shows logs only for a Runbooks it starts. If Runbooks is already running, the command hands the runbook to it and exits.

What it does

Like code ., runbooks open gives you your prompt back right away without printing anything. Runbooks then carries on in the background:

1. For a remote source, it clones the repository that holds the runbook. If the download fails, for example because a private repo has no token, the app shows an error dialog that explains why.
2. It opens the Runbooks window and renders the runbook.mdx file.
3. It keeps running until you quit it, even if you close the terminal you started it from.

If the app is already running, a second invocation focuses the existing window and opens the new runbook in it. A relative path is resolved from the directory you ran the command in.

Note

The runbooks command that the Linux .deb package puts in /usr/bin runs the app itself, so it holds the terminal and prints the app’s logs until you quit Runbooks. To get the command described here, install it from Runbooks. It goes in /usr/local/bin, which comes before /usr/bin in the default PATH.

Troubleshooting

Nothing happens

The command doesn’t show the app’s output, so a launch that fails is silent. Run the same command again with --verbose to see the app’s logs in the terminal. If Runbooks is already running, even with no window, quit it first, or --verbose hands the runbook to it and exits without showing its logs. To quit a Runbooks with no window, end its process in Activity Monitor on macOS, your system monitor on Linux, or Task Manager on Windows.

“Runbooks was not found”

The runbooks command records where Runbooks is installed. If you moved or reinstalled Runbooks, open it and install the command again.

Runbook not found

Check that the path points to a runbook.mdx file or a directory containing one. For a remote source, check that the path exists at the branch, tag or commit you named. A source in go-getter syntax without ?ref= reads the repo’s default branch.

Authentication errors for remote runbooks

If you see “authentication required”, set the token for the git host as described in Authentication for private repos.

Run from a folder that was deleted

If your terminal is still in a folder that has since been deleted (a removed git worktree, for example), your shell prints a warning like this when you run runbooks:

shell-init: error retrieving current directory: getcwd: cannot access parent directories: No such file or directory

Runbooks still starts, or focuses the window that is already open. A relative path such as runbooks open . usually still points into the deleted folder, so the app shows “This path no longer exists” unless a folder has been created again at that path. Some shells can’t say which folder they were in (zsh -c started from the deleted folder, for example), and then relative paths resolve against your home folder. Either way, cd into a folder that exists, or pass an absolute path.