Skip to content

Environment Variables

Jump to bottom
Gubarz edited this page May 31, 2026 · 1 revision

Environment Variables

CheatMD reads a handful of environment variables directly, lets you override every config setting via a CHEATMD_* variable, and exposes your environment to cheats during variable resolution. This page lists them all.

Precedence

From highest to lowest priority:

  1. Command-line flags (e.g. --copy, --query)
  2. CHEATMD_* environment variables
  3. ~/.config/cheatmd/cheatmd.yaml (or ~/cheatmd.yaml)
  4. Built-in defaults

Directly-read variables

Variable Purpose
SHELL Default shell used to run commands and variable scripts (sh -c). Used as the default for the shell setting — a config file or CHEATMD_SHELL overrides it.
XDG_DATA_HOME Base directory for user data: execution history ($XDG_DATA_HOME/cheatmd/history.jsonl), chain state, and the default cheats directory. Falls back to ~/.local/share when unset.
HISTFILE Location of your shell history file, read by the substitute search (Ctrl-T) when history is an enabled source.
HOME (USERPROFILE on Windows) Resolves ~, the config directory (~/.config/cheatmd), and the data directory.

Variables that pre-fill cheat prompts

When CheatMD resolves a variable, any environment variable whose name matches the cheat variable's name pre-fills that prompt. For example, with a cheat variable domain, exporting domain=example.com pre-fills the input (and with auto_continue: true, accepts it without prompting). Your full environment is also offered as a source in the substitute-search picker and in path completion.

Cheats inherit your full environment. Commands run as child processes with os.Environ(), so anything exported into your shell is visible to executed commands.

Set by CheatMD (not read)

Variable Purpose
GIT_TERMINAL_PROMPT=0 Set on the git clone child during cheatmd packs install/update so a clone never blocks waiting for credentials.

CHEATMD_* config overrides

Every setting in Configuration can be set from the environment by prefixing its key with CHEATMD_ and upper-casing it. These override the config file and defaults.

CHEATMD_OUTPUT=copy cheatmd          # copy the selected command instead of printing
CHEATMD_AUTO_SELECT=true cheatmd -q "docker ps"
CHEATMD_HISTORY_MAX=500 cheatmd --history

Core

Variable Config key Type
CHEATMD_PATH path string
CHEATMD_REGISTRY_URL registry_url string
CHEATMD_OUTPUT output print | copy | exec
CHEATMD_SHELL shell string
CHEATMD_EDITOR editor string
CHEATMD_PRE_HOOK pre_hook string
CHEATMD_POST_HOOK post_hook string
CHEATMD_REQUIRE_CHEAT_BLOCK require_cheat_block bool
CHEATMD_ALLOW_UNDECLARED_VARS allow_undeclared_vars bool
CHEATMD_VAR_SYNTAX var_syntax dollar | angle | both
CHEATMD_AUTO_SELECT auto_select bool
CHEATMD_AUTO_CONTINUE auto_continue bool

Keybindings

Variable Config key
CHEATMD_KEY_WIDGET key_widget
CHEATMD_KEY_OPEN key_open
CHEATMD_KEY_SUBSTITUTE key_substitute
CHEATMD_KEY_PREVIEW key_preview
CHEATMD_KEY_HISTORY key_history

History & search

Variable Config key Type
CHEATMD_HISTORY_FILE history_file string
CHEATMD_HISTORY_MAX history_max int
CHEATMD_SUBSTITUTE_SOURCES substitute_sources list — see note

Display

Variable Config key Type
CHEATMD_SHOW_FOLDER show_folder bool
CHEATMD_SHOW_FILE show_file bool
CHEATMD_PREVIEW_HEIGHT preview_height int

Colors

Variable Config key
CHEATMD_COLOR_HEADER color_header
CHEATMD_COLOR_COMMAND color_command
CHEATMD_COLOR_DESC color_desc
CHEATMD_COLOR_PATH color_path
CHEATMD_COLOR_BORDER color_border
CHEATMD_COLOR_CURSOR color_cursor
CHEATMD_COLOR_SELECTED color_selected
CHEATMD_COLOR_DIM color_dim

Columns

Variable Config key Type
CHEATMD_COLUMN_GAP column_gap int
CHEATMD_COLUMN_HEADER column_header int
CHEATMD_COLUMN_DESC column_desc int
CHEATMD_COLUMN_COMMAND column_command int

Note on list-valued settings: CHEATMD_SUBSTITUTE_SOURCES is parsed as a single value, not a list — CHEATMD_SUBSTITUTE_SOURCES="env history" becomes the one entry "env history" rather than ["env", "history"]. To configure multiple substitute sources, set substitute_sources in the config file.

See also

Clone this wiki locally