Files Workspace

When you use a Runbook, you’ll often work with files, whether they’re freshly generated from templates, or cloned from a git repository. The files workspace (labeled just “Files” in the Runbooks UI) is the panel on the right side of the Runbooks UI where all of these files live.

This page explains the two types of files you’ll encounter, when each one appears, and how to work with them.

Two types of files

The files workspace can show two different types of files.

• Generated files
• Repository files

Let’s start by learning about them at a high level.

Generated files

Why use them

You want the runbook to generate new files and expect the user will then perform some out-of-band action with the files, such as manually integrating them into a separate project.

Where they come from

A <Template> block generates files when the user clicks “Generate” (the default target is "generated"). <Command> and <Check> blocks generate files when they run scripts that write to the $GENERATED_FILES environment variable.

Where they’re stored

The files are stored in a generated/ folder on the user’s local machine, relative to the working directory, or whatever folder the user specifies with the output-path flag.

When you see them

After the user clicks “Generate” on a <Template> block, or after a <Command> or <Check> block writes to $GENERATED_FILES, the files workspace is automatically opened.

Repository files

Why use them

You want the user to git clone a repository and then create, modify, or delete files in that repo using subsequent blocks in the runbook. Presumably, after git cloning the files and making changes, the runbook will either git push the changes or open a pull request on them.

Where they come from

Initially, the files are cloned from a git repository via a <GitClone> block.

Any subsequent changes in the files come from a <Template> block that sets target="worktree", or <Command>, and <Check> blocks that run scripts that write to the $REPO_FILES environment variable.

Where they’re stored

The files are stored in a local path (relative to the working directory) specified in the <GitClone> block.

When you see them

After a <GitClone> block successfully clones a repository, the files workspace automatically switches to the Repository tab to show the cloned files.

Tip

If a runbook only produces generated files (no git clone), you’ll only see the “Generated files” tab. If it only clones a repository, you’ll only see the “Repository” tab. When both are present, you can switch between them using the context bar at the top of the workspace.

Generated files

Generated files are new files that the runbook creates on your local machine. There are two main ways they get created:

Template blocks

The Template and TemplateInline blocks generate files from Boilerplate templates. When you fill in the form fields and click “Generate”, the template engine processes your inputs and creates the output files.

<Template id="vpc-setup" path="templates/vpc" />

Template blocks automatically re-render when you change input values, so your generated files stay in sync with the form.

Command and Check blocks with $GENERATED_FILES

Command and Check blocks can write files to the $GENERATED_FILES environment variable to capture them:

<Command
  id="export-terraform"
  command={`tofu output -json > "$GENERATED_FILES/tf-outputs.json"`}
  title="Export Terraform outputs"
/>

Any files written to $GENERATED_FILES automatically appear in the workspace after the block completes successfully.

Where generated files are stored

Generated files are persisted to a folder on your local machine — they’re not ephemeral or stored in memory.

By default, generated files are written to a generated/ folder in the working directory (the directory you run the runbooks command from):

• Directorygenerated/ ← Created in your working directory

  • main.tf
  • variables.tf
  • outputs.tf

You can customize the output location with CLI flags:

# Use a specific working directory
runbooks open my-runbook --working-dir /path/to/project

# Write to a custom subfolder within the working directory
runbooks open my-runbook --output-path ./infrastructure

# Use an isolated temporary directory (auto-cleaned on exit)
runbooks open my-runbook --working-dir-tmp

Tip

The --working-dir-tmp flag is useful for sandboxed execution where you don’t want generated files to persist after you close the runbook.

Subdirectories within templates

If your template or script writes to a subdirectory of $GENERATED_FILES, the subdirectory will be created automatically. For example, if you write to $GENERATED_FILES/config/app.json, the config/ subdirectory will be created automatically.

• Directorygenerated

  • Directoryconfig/

    • app.json
  • main.tf
  • variables.tf
  • outputs.tf

# In a command script
mkdir -p "$GENERATED_FILES/config"
echo '{}' > "$GENERATED_FILES/config/app.json"

Repository files

Repository files come from a git repository that was cloned by a GitClone block in the runbook. When the clone completes, the workspace automatically switches to the Repository tab to show the cloned files.

The Repository tab has two sub-tabs:

All files

The All files tab shows the complete file tree of the cloned repository. Click any file to view its contents with syntax highlighting.

Changed files

The Changed files tab shows a diff view of any files that have been modified since the repository was cloned. This is useful when subsequent blocks in the runbook (like Command or Template blocks with target="worktree") write files into the cloned repository. You’ll see:

• Which files were added, modified, or deleted
• Line-by-line additions and deletions (similar to a GitHub pull request diff)
• A summary of total changes at the top

Note

The “Changed files” tab appears automatically the first time a change is detected. If no files have been modified, the tab will show zero changes.

Multiple repositories

If a runbook clones more than one repository (using multiple GitClone blocks), a dropdown appears in the workspace header letting you switch between them.

Security: Where files can be read and written

Runbooks enforces rules about where files can be read and written:

Path restrictions

Rule	Description
Within working directory	Output paths must resolve to locations within the working directory
No directory traversal	Paths containing .. (like ../../../etc/passwd) are rejected
No system directories	Protected directories like /etc, /usr, C:\Windows are blocked

Workspace API restrictions

The workspace APIs (file tree, file content, and git changes) reject any path containing directory traversal sequences. These APIs are scoped to workspace directories — the paths registered by GitClone blocks and the configured output directory — so they only serve files within the intended workspace.

Note

These restrictions apply to template output paths and workspace APIs. Scripts executed via Command blocks have full filesystem access and can write anywhere the user has permissions.

Protected directories

Runbooks blocks writes to system-critical directories:

• /, /etc, /usr, /bin, /var, /home, /root
• C:\, C:\Windows, C:\Program Files, C:\Users

Next

Now that you understand how the files workspace works, explore the use cases where Runbooks shines.