Instruction mode
By default, Runbooks is interactive. When you click Run, Authenticate, Generate, Clone, or Create PR, the app performs that action on your machine. It executes scripts, captures credentials, renders templates to disk, and talks to git and your git host for you.
In instruction mode, Runbooks performs no actions. Nothing is executed, no credentials are captured, and no files, clones, or pull requests are written. The runbook renders top to bottom with the same prose, and each block shows the command or step to perform by hand, with a button to copy it.
When to use it
Section titled “When to use it”- Windows and other non-POSIX environments. Many runbook scripts and the boilerplate generator assume a Unix-style shell. Instruction mode shows the command so you can run it yourself or adapt it to PowerShell.
- Locked-down or managed machines where the app can’t run scripts, write files, or hold credentials.
- Review before running. Read each command, then run it in your own terminal.
Turning it on
Section titled “Turning it on”Instruction mode is a global setting:
- Open the Menu in the top-right of the window.
- Under Mode, toggle Instruction mode.
Or press Cmd/Ctrl+K and run Turn on Instruction mode from the command palette.
The setting is off by default and is remembered across launches. Turning it off restores the interactive blocks with their state intact. While it is on, a banner at the top of every runbook says that nothing runs automatically.
What each block becomes
Section titled “What each block becomes”| Block | Interactive | Instruction mode |
|---|---|---|
| Command, Check | Run button. The app executes the script. | “Run this command:” or “Run this check:” with the resolved command in a copy block. A nested <Inputs> stays a form above the command. File-backed scripts keep the source viewer. |
| AwsAuth | SSO, profile, or key UI. Captures credentials. | “Log into AWS in the <account> account”, with the configured SSO details. No capture. |
| GoogleAuth | Service account key, Google sign-in, or gcloud config UI. Captures credentials. | “Log into Google Cloud in the <project> project”, noting the region, gcloud configuration, scopes, and the gcloud auth application-default login command. No capture. |
| GitAuth, GitHubAuth, GitLabAuth | OAuth or token entry. Holds a token. | “Log into GitHub” or “Log into GitLab”, noting the scopes the block needs. For GitLab it also names glab auth login. No capture. |
| Inputs | Form you fill | Still a form. Its values are substituted into the displayed commands. |
| Template | Generate button. Renders boilerplate to disk. | The variable form plus a copyable boilerplate invocation. No files written. |
| TemplateInline | Inline rendered preview | The rendered text as a copy block. No files written. |
| GitClone | Clone button | A copyable git clone command, with a sparse-checkout note for sub-paths. |
| GitPullRequest, GitHubPullRequest, GitLabMergeRequest | Create PR or MR button | A copyable gh pr create or glab mr create command, plus a reminder to commit and push your branch first. |
| DirPicker | Cascading directory dropdowns | A text field for the directory path. The path you enter is substituted into later commands. |
| Admonition, Iframe | Callout, embedded page | Unchanged. |
Filling in values
Section titled “Filling in values”Runbooks substitutes every value you supply into the displayed commands. Each
{{ .inputs.* }} or {{ .outputs.* }} reference in a command shows either its
value or, until you supply one, a placeholder such as <bucket>:
Inputsform values are substituted directly into the commands shown, including those from an<Inputs>nested inside a Command or Check. An input you haven’t filled in yet shows as a<name>placeholder. A checkbox always has a value (unchecked isfalse), so it never shows one. An input you’ve left empty stays empty, so conditionals and defaults in the command work out just as they would when it runs. An input used only in template logic, such as the condition of an{{ if ... }}, gets no placeholder. Until you fill it in, that logic is shown as written.- Values produced by an earlier step (a script’s outputs) can’t be known by
the app, because it runs nothing. When a command needs one, instruction mode
shows a small field labeled with the output’s name and the step it comes
from, for example
account_idfrom stepcreate_account. Run that earlier step yourself, then paste the value in. The command updates as you type. A sensitive output always gets a field, even if its step already ran, so the command never shows it.
Tracking your progress
Section titled “Tracking your progress”Each step has a Mark as done checkbox in its top-right corner. Tick it once you’ve performed that step by hand and the block turns green. Your progress is remembered per runbook across reloads, and when you turn instruction mode off and back on.
- Commands are resolved with the same template engine the interactive UI uses to preview them. If that engine is unavailable or can’t render a command, Runbooks falls back to a simpler resolver and shows a small note. That resolver fills in value references only, so template logic such as conditionals and functions may be shown as written.
- Instruction mode changes what the app displays. It is not a headless CLI or CI runner.