Write Your First Runbook

Let’s create a simple runbook from scratch!

Create the runbook file

1. Create a new folder called my-first-runbook.
2. Inside that folder, create a file called runbook.mdx.
3. Create subfolders called scripts and templates/project.
4. Copy/paste the following content into each file:

You can also download the complete example as a zip file.

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](#), 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 available in a subfolder named `generated` folder, relative to where you ran `runbooks` from. You can customize where these files get generated by using the `runbooks --output-path` flag.

## 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 nothing more than a text editor. I typed in some markdown and blocks (e.g. `<Check>` or `<Template>`), refreshed my browser, and verified that things looked the way I wanted. In fact, Runbooks offers `runbooks watch` specially for authors who want fast feedback loops.

You can also use AI to write Runbooks! Give your favorite LLM the [Runbooks LLM instructions](#), along with what you want, and you get a fast starting point.

TODO: Fill in this link.

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

scripts/setup.sh

#!/bin/bash

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

Make the script executable:

chmod +x my-first-runbook/scripts/setup.sh

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

# {{ .ProjectName }}

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

## About

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

{{ if eq .Language "Go" -}}
Go excels at cross-platform compilation and building fast, reliable CLI tools and APIs.
{{- else if eq .Language "Python" -}}
Python's readability and vast ecosystem make it ideal for data science and rapid prototyping.
{{- else if eq .Language "JavaScript" -}}
JavaScript powers the web and runs everywhere from browsers to servers to mobile apps.
{{- else if eq .Language "TypeScript" -}}
TypeScript adds static typing to JavaScript, catching bugs at compile time.
{{- else if eq .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

Open your runbook

Save the files and open the runbook:

runbooks open my-first-runbook/

Your browser will open showing the runbook interface. Follow the steps to execute each block!

Next

This Runbook generates some files. Let’s learn more about how generated files work, and where they live.