Configuration

CheatMD is configured via ~/.config/cheatmd/cheatmd.yaml. All settings are optional - sensible defaults are used when omitted.

Full reference

# Path to your cheats directory (default: current directory)
path: ~/cheats

# What to do with the final command
# "print" (default) - print to stdout
# "copy"  - copy to clipboard
# "exec"  - execute immediately
output: print

# Shell used to run variable commands and exec output
shell: /bin/bash

# If true, only headings with a <!-- cheat --> block are treated as cheats
# If false (default), any heading with a code block is a cheat
require_cheat_block: false

# If true, auto-accept variables pre-filled from environment without prompting
auto_continue: false

# Variable reference syntax in command text
# "dollar" (default) - only $name
# "angle"  - only <name>
# "both"   - accept both forms
var_syntax: dollar

# If true, prompt for any $name/<name> reference that has no var declaration
# If false (default), silently skip undeclared references
allow_undeclared_vars: false

# Pre/post hooks - shell fragments prepended/appended to the final command
pre_hook: ""
post_hook: ""

Key bindings

# Open the substitute search picker (env vars + shell history)
key_substitute: "ctrl+t"

# Open markdown preview overlay
key_preview: "ctrl+y"

# Open execution history
key_history: "ctrl+h"

# Open source file in external viewer/editor
key_open: "ctrl+o"

# Shell widget trigger (readline keyspec)
key_widget: "\C-g"

Substitute search

When a cheat asks for a variable, press the substitute key (default Ctrl-T) to open a fuzzy-search picker over:

• Environment variables - all current env vars
• Shell history assignments - VAR=value, export VAR=value, declare -x VAR=value, and inline assignments found in your shell history

Configure which sources are active:

substitute_sources: ["env", "history"]   # set to [] to disable entirely

Pick a row and its value is loaded into the prompt. Press Enter to accept or edit it first. Esc cancels back to the variable prompt.

History is read from $HISTFILE, falling back to ~/.bash_history or ~/.zsh_history.

Execution history

Every command you run through CheatMD is logged to $XDG_DATA_HOME/cheatmd/history.jsonl (fallback: ~/.local/share/cheatmd/history.jsonl).

Each entry records:

• The final substituted command
• The cheat’s file and header reference
• All resolved variable values

The main picker uses history for frecency ranking: cheats you run often and recently float toward the top.

TUI key reference

See also

• [Shell Integration](/docs/shell integration) - widget, tmux, zellij setup
• Variables - how var_syntax affects detection