cheat/cheat: A Command-Line Cheatsheet Manager That Actually Respects Your Workflow

Hook

The average developer Googles the same Git commands approximately 47 times per year. What if your terminal could remember for you, in your own words, without leaving the shell?

Context

Man pages are comprehensive but verbose. Stack Overflow is helpful but requires context switching to a browser. Built-in help flags (--help) are terse and inconsistent across tools. The documentation paradox facing system administrators and developers is real: commands you use weekly but not daily live in a memory dead zone—familiar enough that looking them up feels wasteful, but obscure enough that you can't recall the exact syntax when you need it.

Traditional solutions fall short. Browser bookmarks scatter knowledge across tabs. Text files in ~/notes become disorganized graveyards. Notebook apps like Notion or Evernote add friction and require leaving the terminal. What's needed is something that lives where developers actually work—the command line—while being flexible enough to accommodate personal preferences and team knowledge sharing. The cheat/cheat project addresses this by treating cheatsheets as first-class citizens of your development environment, stored as plain text files with intelligent tooling around them.

Technical Insight

The brilliance of cheat lies not in complexity, but in its architectural restraint. At its core, cheat is a filesystem-based database with zero serialization overhead. Cheatsheets are just text files named after commands (like 'tar' or 'ffmpeg'), stored in directories defined in ~/.config/cheat/conf.yml. Each directory—called a cheatpath—can have metadata like tags and readonly status.

Here's where the design gets interesting. The configuration file supports multiple cheatpaths with different access levels:

cheatpaths:
  - name: community
    path: ~/.config/cheat/cheatsheets/community
    tags: [community]
    readonly: true
  - name: personal
    path: ~/.config/cheat/cheatsheets/personal
    tags: [personal]
    readonly: false
  - name: work
    path: ~/work/.cheat
    tags: [work]
    readonly: false

This separation enables copy-on-write semantics. When you run cheat -e tar to edit a cheatsheet that exists in a readonly path (like community cheatsheets cloned from GitHub), cheat automatically copies it to your first writable cheatpath. You get the benefit of community-maintained documentation without merge conflict headaches when you add personal annotations. Your edits live separately, and you can sync the community repo independently.

The project-scoped .cheat directory feature mirrors Git's mental model. When you run cheat kubernetes-debug, cheat walks up the directory tree looking for a .cheat folder, similar to how Git finds .git. This means project-specific command references—deployment scripts, custom rake tasks, Makefile targets—can live alongside code without polluting your global cheatsheet namespace. Change directories, get different cheatsheets. It's context-aware documentation that follows your working directory.

Syntax highlighting integration via the Chroma library transforms cheatsheets from plain text into readable, colorized references. Add YAML frontmatter to specify the lexer:

---
syntax: bash
tags: [git, vcs]
---

# Undo last commit but keep changes
git reset --soft HEAD~1

# Interactive rebase last 3 commits
git rebase -i HEAD~3

# Stash with message
git stash push -m "WIP: feature implementation"

The Chroma lexer automatically applies language-specific syntax highlighting when displaying the cheatsheet, making code snippets immediately parseable. Since Chroma supports hundreds of languages, your cheatsheets for Python, SQL, Terraform, or even obscure DSLs get proper treatment.

Search functionality goes beyond simple grep. The cheat -s 'regex pattern' command searches across all cheatsheets with regex support, while cheat -t work filters by tags. You can combine filters: cheat -t kubernetes -s 'pod' finds all pod-related commands in kubernetes-tagged cheatsheets. The tool also supports directory-specific searches with cheat -p personal -s 'docker', letting you scope queries to specific knowledge domains.

What makes this architecture maintainable is its embrace of existing tools. Cheatsheets are just files, so you version them with Git, sync them with Dropbox, or back them up however you normally would. No proprietary database. No export functions. No API rate limits. Your knowledge stays portable across jobs, machines, and decades.

Gotcha

The most glaring limitation is the complete absence of synchronization features. Unlike modern note-taking apps, cheat doesn't sync anything—you're responsible for managing Git repos or file synchronization yourself. For solo developers, this means setting up your own sync strategy. For teams, it means establishing conventions around shared cheatsheet repositories and update schedules. There's no 'official' way to keep personal and team cheatsheets in sync, which can lead to documentation drift.

Search capabilities, while functional, are decidedly 2010s-era. You get regex pattern matching across file contents, but no fuzzy finding, no typo tolerance, no semantic search. If you search for 'compress' you won't find cheatsheets that only mention 'archive' or 'gzip'. The tool is fast and predictable, but lacks the intelligent search features developers now expect from tools like fzf or modern IDEs. For large cheatsheet collections (100+ files), finding the right snippet can require remembering exact terminology or browsing multiple results. Additionally, cheat ships without any cheatsheets—you need to either clone the community repository separately or write everything from scratch, which creates initial setup friction.

Verdict

Use cheat if: You live in the terminal and want command-line documentation that respects plain text and Git workflows. You're a sysadmin juggling dozens of infrequently-used CLI tools. You work on a team that can benefit from shared, version-controlled knowledge bases. You value data portability and don't want vendor lock-in for something as fundamental as documentation. You already use dotfile syncing strategies and can apply the same approach to cheatsheets. Skip cheat if: You need built-in cloud sync and mobile access to your notes. You prefer graphical note-taking apps with rich formatting, images, and tables. You work primarily in IDEs where editor snippets (like VSCode snippets or IntelliJ Live Templates) make more sense. You want zero-configuration solutions—tools like tldr give you instant access to community cheatsheets without any setup. You need semantic search or AI-assisted documentation retrieval. The tool assumes you're comfortable with the command line and manual file organization, which isn't everyone's preferred workflow.