Create a guide

A guide is a short checklist shown next to your demo. The visitor sees the steps you wrote, and each one ticks itself as they do it. Somebody who has never seen your software can get through the parts you wanted them to see.

A VM has at most one guide. It belongs to the VM, not to a build, so a rebuild keeps it.

Open the editor

On the VM's page, press Add guide (or Edit guide once it has one). You can also reach the editor from the Guide column in the project's VM table.

The editor boots a live copy of your VM beside the step list, so you write steps against the real machine. If the VM cannot boot there, the editor offers "Edit without a VM" instead of a dead page.

Draft and published

Your steps are a draft. Visitors see nothing until you press Save & Publish.

The ⋯ menu beside that button holds the rest:

• Edit — the guide's name and its finish card. See Guide settings.
• Test run — walk the guide as a visitor. See Two shortcuts.
• Unpublish — stop delivering it.
• Delete guide — removes the guide completely.

Publishing needs a verified email address.

Write a step

Each step has a title, an optional hint, and one rule for how it ticks.

Field	Notes
Title	What the step is called in the checklist.
Hint shown to the visitor	Optional, one paragraph. Say what to do and why it is interesting.
How it gets ticked	Command, key press, or manual. See below.
Optional	Visitors may skip it.

The three kinds of step

Mode	Ticks when
Command	The visitor runs a command line you name.
Key press	The visitor presses a key.
Manual	Not auto-detected, the visitor presses MARK DONE in the guide panel.

Command steps

A command step expects vistor to run the command and watches if it has been done.

1 — The visitor types (required). defines what we expect vistor to type in the console and how that command can be detected:

Match mode	Ticks on
EXACTLY THIS	That command line, exactly.
STARTS WITH	Any line starting with what you wrote.
PATTERN	A regular expression, for when several spellings should count.

2 — And the output contains (optional). Some text the command must print. Leave it blank and running the command is enough.

Only tick if the command succeeds (optional). The command must exit cleanly.

Watch for values that change

The editor warns when a pattern or an output check contains something that will not be the same when a visitor runs it — a date, a path with your username, a version number. Those steps never tick.

Key press steps

Some steps are not commands but key presses, for example Ctrl-R to open the shell history, s to sort inside a file manager, or Tab to complete the path.

Both single key and modifier (ctrl or alt) + a key combinations are supported, for example:

Key	Write it as
A single key	the character itself — s, S, /, ?, 1. Capitals matter: S is Shift and S, a different key from s
Ctrl and a letter	CTRL-R, Ctrl+R, C-r or ^r — any letter A–Z, any capitalisation
Alt and a letter	ALT-I, Alt+I or M-i — same
Tab	Tab
Enter	Enter or Return
Esc	Esc or Escape
Space	Space

A single key is just a character

There is nothing in a keystroke that says whether the visitor pressed s inside an app or typed it as part of a command, so a single-key step also ticks if they type that character on its own before reaching the step. Steps for keys with a modifier (CTRL-R) do not have this, because nothing else sends those bytes.

Alt on a Mac

The demo's terminal treats the Option key as Alt, so an ALT-I step ticks for Mac visitors too. That is also why Option does not compose characters (é, ˆ) inside a demo — it is sent to the guest instead, which is what a terminal app expects.

Manual steps

For steps that cannot be detected or must be done outside the terminal, the visitor gets a MARK DONE button. A manual step must have a hint.

Order

At the top of the step list:

• FIXED — the steps are numbered and the visitor works through them in order.
• ANY — no order. Use it when they are independent things to try.

Drag a step, or use the ▲ ▼ buttons, to reorder.

Two shortcuts worth using

• Capture chips. Run a command in the editor's live VM and turn it into a step with one click, with the pattern already filled in from what you actually ran. Select text in its output and turn that into the output check.
• Test run, in the ⋯ menu. Runs the real visitor checklist over a fresh boot of the VM, so you see what they will see.

Guide settings

Edit in the ⋯ menu opens the guide's own settings:

Field	Limit
Guide name	200 characters. Visitors see it over the checklist.
Finish card label	120 characters
Finish card URL	1024 characters, must start with http:// or https://

The finish card is what the visitor gets when the last step is done — a link to your docs, repo, or the sign-up page.

Step titles, hints and patterns are capped at 4000 characters each.

What visitors see

The checklist sits beside the terminal on a wide screen, under it on a narrow one. Each step shows the command to type, ticked steps grey out. When the last step is done, the terminal prints ✓ quickstart complete and the finish card appears with your link on it.

You control how it appears in an embed with the guide option: 'auto' (open), 'collapsed' (a [ 0/4 ] GUIDE pill the visitor opens), or 'off'. See Embedding.

Checks and stats

The automatic check runs after every build of a guided VM. We replay the guide in the VM and try to reproduce the visitor journey as they follow the guide. We let you know if anything breaks.

Some steps cannot be replayed and are reported as not checked, never as failed:

• manual steps,
• key press steps,
• STARTS WITH and PATTERN steps
• a step whose command gave no exit code

A step that diverges never fails the build. If the rebuild was automatic, we email you the build report.

Stats on the VM's page show how many visitors started the guide, how many finished, and where they stopped, over the last 30 days.

Next

• Automatic builds — and what the guide check does on each one.
• Embedding — how the checklist appears on your site.