Write your first runbook

This page builds a small runbook from scratch. You can also download the complete example as a zip file.

Create the runbook files

1. Create a new folder called my-first-runbook.
2. Inside that folder, create the subfolders checks, scripts and templates/project.
3. Create each of the files below with the content shown.

runbook.mdx

# My First Runbook

Welcome to your first runbook! Let's walk through the key features of Runbooks.

## Full markdown support

The first thing to point out is that you have access to the _full set_ ~~of~~ **markdown capabilities** ❤️. Here are some commonly used elements, though almost all of [GitHub-Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) is supported:

| Element | Syntax | Description |
|---------|--------|-------------|
| Headings | `# H1` `## H2` `### H3` | Create section titles and hierarchy |
| Bold | `**text**` | Emphasize important text |
| Italic | `*text*` or `_text_` | Add subtle emphasis |
| Links | `[text](url)` | Create clickable hyperlinks |
| Images | `![alt](url)` | Embed images in your document |

### Admonitions

In addition to full markdown support, you can also include an [Admonition block](https://runbooks.gruntwork.io/authoring/blocks/admonition/) like this:

<Admonition type="info" title="Before You Begin" description="This is an Admonition block. Notice that it even supports _inline markdown_!" />

## Checks

When users are consuming a runbook, It can be helpful to "check" that they are prepared to succeed, or after using a runbook, that they did in fact succeed. This is the function of [Check blocks](https://runbooks.gruntwork.io/authoring/blocks/check/).

In this example, we're going to verify that git is installed:

<Check
    id="check-git"
    command="git --version"
    title="Check if Git is installed"
    description="We need Git for version control"
    successMessage="Git is installed!"
    failMessage="Git is not installed. Please install it from https://git-scm.com/"
/>

That was a pretty simple check, so now let's load our check from a script, and allow users to _customize_ that script on the fly.

<Check id="check-git-version" path="checks/check-git-version.sh" title="Check Git Version" description="Verify that you're running a specific version of git" failMessage="Hmm, your git version seems off. Try again." successMessage="Success! Well now, look who's got the expected git version.">
  <Inputs id="git-version-inputs">
    ```yaml
    variables:
      - name: GitVersion
        type: string
        description: "The exact git version you expect to have installed (e.g., 2.39.0)"
        validations:
        - required
        default: "2.39.0"
    ```
  </Inputs>
</Check>

If you look at the source code for this runbook, you'll see that we declare the inputs (or variables) we want, and Runbooks renders a web form automatically:

```yaml
variables:
- name: GitVersion
  type: string
  description: "The exact git version you expect to have installed (e.g., 2.39.0)"
  validations:
  - required
  default: "2.39.0"
```

We declare the variables using [Gruntwork Boilerplate syntax](https://runbooks.gruntwork.io/authoring/boilerplate/), and we have significant control over how the webform renders based on what the [Inputs block](https://runbooks.gruntwork.io/authoring/blocks/inputs/) supports.

## Generate files

Now let's generate some files. We're going to specify a Gruntwork Boilerplate template, that includes a declaration of the variables in that template, and the template files themselves.

Runbooks will then render a web form automatically and generate the files for us!

<Template id="project" path="templates/project" />

<Admonition type="info" title="Templates update in real time" description="Try updating the author name and programming language, and notice how the rendered template changes in real time." />

On your local machine, all the newly generated files are saved in a subfolder of the folder that contains this runbook.

## Run commands

Runbooks also gives you the [Command block](https://runbooks.gruntwork.io/authoring/blocks/command/), which allows you to run arbitrary scripts.

You can even parameterize the scripts with a custom set of inputs, or any of the inputs we collected above.

<Command
    id="run-setup"
    path="scripts/setup.sh"
    inputsId="project"
    title="Run Project Setup"
    description="Creates your project structure"
    successMessage="Project setup complete!"
    failMessage="Setup failed. Check the logs for details."
/>

Commands are useful when you need to do things like:

- Make an API call
- Install tools locally
- Run commands locally

Whereas Checks blocks are focused on _reading_ the current state of the world, Command blocks are focused on _mutating_ the state of the world.

## Congratulations!

<Command
    id="final-message"
    command="echo '🎉 Congratulations! You finished using your first runbook!'"
    title="Show Success Message"
/>

**Great job!**

Everything above was built in a text editor. I typed in some markdown and blocks (e.g. `<Check>` or `<Template>`), reloaded the runbook, and verified that things looked the way I wanted. To have Runbooks reload the runbook each time you save, open it with `runbooks open --watch`.

If you'd like to learn more about Runbooks, head back to the [Runbooks docs](https://runbooks.gruntwork.io).

checks/check-git-version.sh

#!/bin/bash

# Git Version Validation Script
# This script checks if the user has the expected version of git installed

echo "🔍 Checking git version..."
echo "📋 Expected version: {{ .inputs.GitVersion }}"

# Get the installed git version (extract just the version number, e.g., "2.39.5")
INSTALLED_VERSION=$(git --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)

if [ -z "$INSTALLED_VERSION" ]; then
    echo "❌ Git is not installed"
    exit 1
fi

echo "💻 Installed version: $INSTALLED_VERSION"

# Compare versions
if [ "$INSTALLED_VERSION" = "{{ .inputs.GitVersion }}" ]; then
    echo "✅ You are running the exact expected git version!"
    exit 0
else
    echo "⚠️ Version mismatch: expected {{ .inputs.GitVersion }}, but found $INSTALLED_VERSION"
    exit 1
fi

scripts/setup.sh

#!/bin/bash

echo "🚀 Setting up project: {{ .inputs.ProjectName }}"
echo ""
echo "👋 Welcome, {{ .inputs.Author }}!"
echo "📦 Primary language: {{ .inputs.Language }}"
echo ""
echo "✅ Project setup complete!"

templates/project/boilerplate.yml

variables:
  - name: ProjectName
    type: string
    description: What would you like to call your project?
    default: my-awesome-project
    validations:
      - required

  - name: Author
    type: string
    description: What's your first name?

  - name: Language
    type: enum
    description: What's your favorite programming language?
    options:
      - Go
      - Python
      - JavaScript
      - TypeScript
      - Rust
    default: Go

templates/project/README.md

# {{ .inputs.ProjectName }}

Created by **{{ .inputs.Author }}**

## About

This project is built with {{ .inputs.Language }}.

{{ if eq .inputs.Language "Go" -}}
Go excels at cross-platform compilation and building fast, reliable CLI tools and APIs.
{{- else if eq .inputs.Language "Python" -}}
Python's readability and vast ecosystem make it ideal for data science and rapid prototyping.
{{- else if eq .inputs.Language "JavaScript" -}}
JavaScript powers the web and runs everywhere from browsers to servers to mobile apps.
{{- else if eq .inputs.Language "TypeScript" -}}
TypeScript adds static typing to JavaScript, catching bugs at compile time.
{{- else if eq .inputs.Language "Rust" -}}
Rust delivers C-level performance with memory safety guaranteed at compile time.
{{- end }}

## Getting Started

1. Clone this repository
2. Install dependencies
3. Start building!

templates/project/.gitignore

# Build outputs
dist/
build/
*.exe

The scripts don’t need to be executable. Runbooks reads each one and runs it with the interpreter its first line names.

Open your runbook

Save the files and open the runbook:

runbooks open my-first-runbook/

If your terminal can’t find runbooks, install the command, or choose Open Runbook on the app’s welcome screen and pick the folder.

The Runbooks window opens and shows the runbook. Work through it from top to bottom and run each block.

Next

This runbook generates some files. The files workspace page explains where generated files and cloned repositories show up in the Runbooks UI.