← Home Docs
GitHub wiki

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

VariablePurpose
SHELLDefault 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_HOMEBase 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.
HISTFILELocation 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)

VariablePurpose
GIT_TERMINAL_PROMPT=0Set 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

VariableConfig keyType
CHEATMD_PATHpathstring
CHEATMD_REGISTRY_URLregistry_urlstring
CHEATMD_OUTPUToutputprint | copy | exec
CHEATMD_SHELLshellstring
CHEATMD_EDITOReditorstring
CHEATMD_PRE_HOOKpre_hookstring
CHEATMD_POST_HOOKpost_hookstring
CHEATMD_REQUIRE_CHEAT_BLOCKrequire_cheat_blockbool
CHEATMD_ALLOW_UNDECLARED_VARSallow_undeclared_varsbool
CHEATMD_VAR_SYNTAXvar_syntaxdollar | angle | both
CHEATMD_AUTO_SELECTauto_selectbool
CHEATMD_AUTO_CONTINUEauto_continuebool

Keybindings

VariableConfig key
CHEATMD_KEY_WIDGETkey_widget
CHEATMD_KEY_OPENkey_open
CHEATMD_KEY_SUBSTITUTEkey_substitute
CHEATMD_KEY_PREVIEWkey_preview
CHEATMD_KEY_HISTORYkey_history

History & search

VariableConfig keyType
CHEATMD_HISTORY_FILEhistory_filestring
CHEATMD_HISTORY_MAXhistory_maxint
CHEATMD_SUBSTITUTE_SOURCESsubstitute_sourceslist — see note

Display

VariableConfig keyType
CHEATMD_SHOW_FOLDERshow_folderbool
CHEATMD_SHOW_FILEshow_filebool
CHEATMD_PREVIEW_HEIGHTpreview_heightint

Colors

VariableConfig key
CHEATMD_COLOR_HEADERcolor_header
CHEATMD_COLOR_COMMANDcolor_command
CHEATMD_COLOR_DESCcolor_desc
CHEATMD_COLOR_PATHcolor_path
CHEATMD_COLOR_BORDERcolor_border
CHEATMD_COLOR_CURSORcolor_cursor
CHEATMD_COLOR_SELECTEDcolor_selected
CHEATMD_COLOR_DIMcolor_dim

Columns

VariableConfig keyType
CHEATMD_COLUMN_GAPcolumn_gapint
CHEATMD_COLUMN_HEADERcolumn_headerint
CHEATMD_COLUMN_DESCcolumn_descint
CHEATMD_COLUMN_COMMANDcolumn_commandint

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

  • [[Configuration]] - the cheatmd.yaml settings these variables override
  • [[Getting Started]] - first-run setup and the registry (CHEATMD_REGISTRY_URL)
  • [[Shell Integration]] - shell widget that uses key_widget / CHEATMD_KEY_WIDGET