Installation

Download the latest version of Runbooks from the GitHub releases page.

macOS

Runbooks requires macOS 13 (Ventura) or later.

Download the .dmg file for your Mac from the latest GitHub release:

• Apple Silicon: Runbooks-x.y.z-mac-arm64.dmg
• Intel: Runbooks-x.y.z-mac-x64.dmg

Open the .dmg file and drag Runbooks into your Applications folder.

Tip

To find out which chip you have, click the Apple menu and select About This Mac. A chip named “Apple M1” or similar needs the Apple Silicon version. “Intel” needs the Intel version.

Linux

Download one of the following from the latest GitHub release:

• Runbooks-x.y.z-linux-x86_64.AppImage runs on most Linux distributions without installation. Mark it as executable and run it:

  chmod +x Runbooks-x.y.z-linux-x86_64.AppImage
  ./Runbooks-x.y.z-linux-x86_64.AppImage

• Runbooks-x.y.z-linux-amd64.deb is for Debian and Ubuntu. Install it with:

  sudo dpkg -i Runbooks-x.y.z-linux-amd64.deb

After installing the .deb package, launch Runbooks from your application menu or by running runbooks in a terminal. The .deb package’s runbooks command runs the app itself, so it holds the terminal and prints the app’s logs until you quit Runbooks. For a runbooks command that gives you your prompt back right away, install the command from Runbooks, then open a new terminal.

Windows

Download the installer, Runbooks-x.y.z-win-x64.exe, from the latest GitHub release.

Run the installer and follow its prompts. Then launch Runbooks from the Start menu or desktop shortcut.

Installing the runbooks command

To open runbooks from a terminal with the runbooks command, click Install command line tool on the welcome screen. You can also choose Install ‘runbooks’ command in PATH from the Runbooks menu on macOS, from the Help menu on Linux and Windows, or from the command palette (Cmd/Ctrl+K).

• On macOS and Linux, Runbooks writes a small launcher script to /usr/local/bin/runbooks. If you can’t write to that folder, you’re asked for your administrator password.
• On Windows, Runbooks writes runbooks.cmd to %LOCALAPPDATA%\Runbooks\bin and adds that folder to your user PATH. Open a new terminal to pick up the change.

The runbooks command starts Runbooks and gives you your prompt back right away. If yours holds the terminal and prints the app’s logs until you quit Runbooks, it is an outdated launcher. Install the command again to replace it. The welcome screen shows Install command line tool while the launcher is outdated.

The launcher records where the app is installed. If you move Runbooks, or switch to a different AppImage file, install the command again to update it. On macOS, move Runbooks to your Applications folder before you install the command.

To remove the command, choose Uninstall ‘runbooks’ command from PATH from the same menu or from the command palette.

Caution

If /usr/local/bin/runbooks already exists and Runbooks didn’t create it (for example, an older Runbooks CLI), Runbooks won’t overwrite or remove it. Installing shows an error instead. To install the command, remove or rename the existing file first.

Building from source

To build the app yourself, install mise first. It installs the other tools the build needs.

1. Clone the repository:

   git clone https://github.com/gruntwork-io/runbooks.git
   cd runbooks

2. Install tool versions and dependencies:

   mise install
   bun install

3. Build and package the app for your platform:

   just package

   On macOS, just package needs an Apple Developer ID certificate. Without one, run just package-local, which signs the app ad hoc.

   The packaged app is written to the out/ directory.

Verifying installation

Open Runbooks. You should see the welcome screen.

Next

Next, write your first runbook.