Chains

Chains are ordered multi-step workflows. Each step is a separate cheat that advances to the next step on the following CheatMD launch.

Defining a chain

Mark each step with chain <name> <step> in its <!-- cheat --> block:

## Release: choose version

```sh title:"Show release version"
echo $version
```
<!-- cheat
chain release 1
var version --- --header "Version"
-->

## Release: build

```sh title:"Build release artifact"
make build VERSION=$version
```
<!-- cheat
chain release 2
var version --- --header "Version"
-->

## Release: publish

```sh title:"Publish release artifact"
make publish VERSION=$version
```
<!-- cheat
chain release 3
var version --- --header "Version"
-->

Using chains

In the picker, search chains with /chain:

/chain              # Show all chains
/chain release      # Filter to the "release" chain

Selecting the chain runs the next pending step and exits. The next plain cheatmd launch resumes at the following step. You can run other cheats in between - chain progress persists.

After the last step completes, the chain resets to step 1.

Resetting progress

cheatmd chain reset          # Reset all chains for this cheats path
cheatmd chain reset release  # Reset one chain

Rules

• Chain names are whitespace-delimited identifiers.
• Step numbers are 1-indexed integers and must be sequential (1, 2, 3…).
• Chain state is per cheats path - different directories track progress independently.
• A cheat can belong to only one chain.
• Each step can have its own variables, imports, and conditionals.

Linting

The Linting checks for:

• Missing steps (e.g., chain has step 1 and 3 but no 2)
• Duplicate step numbers within the same chain
• Malformed chain lines (wrong number of arguments, non-numeric step)

See also

• [Writing Cheats](/docs/writing cheats) - basic cheat structure
• Recipes - chain example patterns