cheatmd

README

CheatMD

Executable Markdown cheatsheets. Write readable docs, run interactive commands.

Install

go install github.com/cheatmd-dev/cheatmd/cmd/cheatmd@latest

Quick Start

cheatmd                    # Browse current directory
cheatmd ~/cheats           # Browse specific directory
cheatmd -q "docker"        # Start with search query
cheatmd --history          # Re-run from execution history
cheatmd convert tldr tar.md -o ~/cheats/tar.md # convert a tldr cheat
cheatmd packs list         # List installable cheat packs from the registry
cheatmd packs install      # Pick and install cheat packs (interactive)

First run

The first time you run cheatmd (before a config file exists) on an interactive terminal, it offers to set you up: it writes a config to ~/.config/cheatmd/cheatmd.yaml and lets you pick starter cheat packs to install from the registry into ~/.local/share/cheatmd/cheats. Pick packs from the checklist with space, confirm with enter. Point registry_url at a private/self-hosted registry.yaml to customize the offered packs. Setup is skipped in headless/piped invocations.

You can install packs any time with the packs command — it doesn't depend on the first-run prompt:

cheatmd packs list                 # show available packs (and which are installed)
cheatmd packs install              # interactive picker
cheatmd packs install git docker   # install specific packs by name

Features

Write cheats as Markdown

Any heading with a code block is a cheat. Variables like $container become interactive prompts powered by shell commands:

## Docker: exec into container

```sh title:"Execute shell in container"
docker exec -it $container /bin/sh
```
<!-- cheat
var container = docker ps --format "{{.Names}}" --- --header "Select container"
-->

Fuzzy search with frecency

Type to filter across titles, commands, descriptions, and tags. Cheats you run often and recently float to the top.

Variables from shell output

Variable values come from shell command output - 0 lines gives a text prompt, 1 line pre-fills, 2+ lines give a filterable picker.

Reusable modules

Export a variable definition once, import it in any cheat:

<!-- cheat
export docker_container
var container = docker ps --format "{{.Names}}"
-->

Chains

Multi-step workflows that advance one step per launch:

/chain release     <- search chains in the picker

Tags

Cheats are tagged automatically from folder paths, YAML front matter, footer blocks, inline #hashtags, and heading text - all searchable from the picker.

Shell integration

Embed CheatMD directly into your shell prompt, tmux, or Zellij:

eval "$(cheatmd widget bash)"   # Ctrl+G opens the selector

Linting

Validate DSL syntax, imports, chains, and undeclared variables:

cheatmd --lint ~/cheats

Language-aware: shell builtins like $HOME and PowerShell $true won't trigger false positives.

Dump

Export cheat metadata as JSON or CSV for indexing and tooling:

cheatmd dump ~/cheats --json

Convert existing cheatsheets

Bring existing collections into CheatMD:

cheatmd convert navi ~/navi-cheats -o ~/cheats
cheatmd convert tldr ~/tldr/pages/common/tar.md -o ~/cheats/tar.md
cheatmd convert cheat ~/cheat/cheatsheets -o ~/cheats

Supported inputs are navi, tldr, and cheat/cheatsheets.

Headless Mode

Run CheatMD without a TUI to integrate with other tools (like VS Code or Obsidian) using a JSON-RPC interface over standard I/O:

cheatmd --headless -q "docker exec"

Editor Extensions

• VS Code - syntax highlighting, lint diagnostics, completion, and CodeLens execution.
• Neovim - syntax highlighting, async diagnostics, completion, and :CheatMDRun.
• Obsidian - inline run buttons, lint status, execution results, and variable autocomplete.

TUI Keys

Key	Action
Ctrl-H	Execution history
Ctrl-T	Substitute search (env + shell history)
Ctrl-Y	Markdown preview
Ctrl-O	Open source file in editor
Tab	Path completion / copy selection

Documentation

Full documentation lives in the Wiki:

• Getting Started - first steps with CheatMD
• Writing Cheats - heading structure, code blocks, metadata
• Variables - prompt, shell, and literal forms
• Selector Options - --header, --column, --map
• Conditionals - if / fi branching
• Modules - export / import
• Chains - multi-step workflows
• Tags - five tag sources
• Configuration - cheatmd.yaml reference
• Shell Integration - widget, tmux, zellij
• Linting - syntax and reference validation
• Dump - metadata export
• Convert - import navi, tldr, and cheat/cheatsheets collections
• Headless Mode - JSON-RPC programmatic interface
• Recipes - copy-pasteable patterns

Contributing

See CONTRIBUTING.md.

License

MIT