cheat: How Interactive Cheatsheets Beat Man Pages for Command-Line Reference
Hook
You’ve Googled “tar extract flags” at least a dozen times in your career. So has every other sysadmin. What if that knowledge lived in version-controlled text files that followed you across projects and machines?
Context
Man pages are comprehensive but verbose. The --help flag is terse but inconsistent. Online documentation requires context-switching to a browser. For command-line tools you use frequently—but not frequently enough to memorize every flag—there’s a gap between needing quick reference and wanting to avoid the cognitive overhead of full documentation.
The cheat project addresses this by turning your terminal into a searchable, customizable knowledge base. Built in Go with 13,000+ GitHub stars, it manages plain-text cheatsheets that live alongside your code, support syntax highlighting via the Chroma library, and can be scoped to specific projects or shared across your entire team through version control. Unlike static documentation, these cheatsheets are interactive: you can search them with regex, filter by tags, and edit them inline without leaving the terminal.
Technical Insight
At its core, cheat implements a multi-repository architecture that cleanly separates concerns between community-maintained references and personal notes. The tool is configured via a YAML file that defines “cheatpaths”—directories containing cheatsheet files. Each cheatpath has a name, filesystem location, optional tags, and a crucial readonly flag that prevents accidental edits to upstream repositories:
cheatpaths:
- name: community
path: ~/documents/cheat/community
tags: [ community ]
readonly: true
- name: personal
path: ~/documents/cheat/personal
tags: [ personal ]
readonly: falseThis design elegantly solves the merge-conflict problem that plagues shared documentation. When you attempt to edit a cheatsheet on a read-only path, cheat transparently copies it to a writable directory first. You get the benefit of community knowledge without the friction of maintaining a fork.
Cheatsheets themselves are plain-text files named after the command they document. No file extensions, no proprietary formats—just text that any editor can modify and any version control system can track. The magic happens in the optional YAML frontmatter:
---
syntax: javascript
tags: [ array, map ]
---
// To map over an array:
const squares = [1, 2, 3, 4].map(x => x * x);The syntax field leverages Chroma’s extensive lexer library to provide context-aware highlighting for dozens of languages. Tags enable powerful filtering: cheat -l -t networking lists only networking-related sheets, while cheat -p personal -t networking --regex -s '(?:[0-9]{1,3}\.){3}[0-9]{1,3}' chains filters to find IP addresses in your personal networking cheatsheets.
Perhaps the cleverest architectural decision is directory-scoped cheatpaths. Like Git’s .git discovery mechanism, cheat searches the current working directory and its ancestors for a .cheat folder. Find one, and those cheatsheets become temporarily available without modifying your global config. This transforms cheatsheets from personal reference material into living project documentation. A Django project might include a .cheat directory with sheets for custom management commands. A Kubernetes deployment could ship with cluster-specific kubectl examples. The documentation lives where the code lives, versioned together, discovered automatically.
The shell completion system deserves special mention. Rather than static flag completion, cheat --completion bash generates dynamic completions that include actual cheatsheet names and tags from your configured paths. When you type cheat <tab>, you see available sheets, not just command flags. It’s a small detail that dramatically improves the daily workflow.
Gotcha
The plain-text architecture is both cheat’s greatest strength and its most obvious limitation. There’s no built-in synchronization mechanism—if you work across multiple machines, you’re responsible for managing Git repositories or file syncing yourself. For developers already comfortable with version control, this is a feature (you control the sync strategy). For others, it’s manual overhead that web-based tools like Notion or Confluence handle automatically.
The text-only format also means no support for rich media. You can’t embed diagrams, screenshots, or formatted tables beyond what ASCII art provides. Syntax highlighting helps with code blocks, but if your mental model depends on visual architecture diagrams, you’ll need a supplementary tool. The .cheat directory discovery, while powerful, doesn’t support exclusion patterns—in a large monorepo, you can’t easily ignore specific subdirectories where .cheat folders might create noise. You either get all discovered directories or none.
Verdict
Use cheat if you live in the terminal and regularly context-switch between projects that use different tooling. It shines for sysadmins managing multiple environments, polyglot developers juggling language-specific CLIs, or teams that want project-specific command references versioned alongside code. The multi-repository design and directory-scoped contexts make it particularly valuable when you need to separate community knowledge from proprietary internal commands. Skip it if you prefer web-based tools with rich formatting, need real-time collaboration features beyond what Git provides, or primarily work in GUI environments where terminal access isn’t part of your daily flow. Also skip if you’re looking for beginner-friendly, crowdsourced content with consistent formatting—tldr is better for that use case. cheat assumes you’re comfortable curating your own knowledge base and rewards that investment with flexibility.
