# cheat: command-line cheatsheets for commands you use too rarely to remember

> cheat stores plain-text cheatsheet files on configurable cheatpaths and prints them from the terminal. It solves the half-remembered-flag problem for shell users, and it asks you to curate your own sheets.

**cheat/cheat** — cheat allows you to create and view interactive cheatsheets on the command-line. It was designed to help remind *nix system administrators of options for commands that they use frequently, but not frequently enough to remember.

- Repository: https://github.com/cheat/cheat
- Stars: 13,472 · Forks: 851
- Language: Go
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/cheat-cheat

## The problem cheat solves, and who it is actually for

Most command-line tools have a long tail of flags that you touch a few times a year. tar is the canonical example, and the README leans on that joke directly: the next time you are forced to disarm a nuclear weapon without consulting Google, you may run cheat tar. The tool is aimed at *nix system administrators who use a command often enough to know it exists but not often enough to have internalised its options. The output is a plain-text list of invocations with short comments, not a manual page and not a tutorial.

That framing matters when you decide whether to adopt it. cheat is not a documentation generator and it does not read man pages or --help output. It is a lookup table you build. The README states plainly that the cheat executable includes no cheatsheets, and that community-sourced cheatsheets are available in a separate repository, with an offer to install them the first time you run cheat. So the value you get on day one depends entirely on somebody else's sheets, and the value you get in month six depends on whether you wrote your own.

## How cheat resolves a name to a file

A cheatsheet is a plain-text file with no file extension, named after the command used to view it. cheat tar reads a file called tar; cheat foo/bar reads a file called bar inside a foo subdirectory. Directories that hold sheets are called cheatpaths, and they are declared in conf.yml with a name, a path, a list of tags and a readonly boolean.

Resolution walks the configured cheatpaths, and a sheet can carry YAML frontmatter that assigns tags and a syntax lexer. Syntax highlighting comes from Chroma, and the syntax value accepts any lexer name Chroma supports. Two behaviours are worth knowing before you rely on the tool. First, a readonly: true path is never written to; if you try to edit a sheet that lives there, cheat copies it to a writeable directory first and opens the copy, which is how the project avoids merge conflicts against an upstream sheet repository. Second, cheat looks for a .cheat directory in the current working directory and its ancestors, the same way git finds .git, and temporarily adds the nearest one to the cheatpath list. That makes project-local sheets possible without touching global config.

Search is a separate path through the same data: cheat -s matches a phrase, and adding -r treats the argument as a regular expression. Filters compose, so you can restrict to a cheatpath, a tag and a regex in one invocation. The README gives the example of finding sheets on the personal path tagged networking that contain an IP address.

## Installing cheat and viewing your first sheet

The README does not carry install instructions inline; it points to INSTALLING.md in the repository, and the releases page is the other documented source for binaries. The repository also ships a Dockerfile, but its own comment says the image is not used anywhere in the build pipeline and exists to facilitate ad-hoc experimentation in a sandboxed environment during development, so treat it as a development convenience rather than a supported deployment path.

Once a binary is on your PATH, the shortest useful session is a lookup. The README's first example is:

```bash
cheat tar
```

You should see the sheet for tar printed to your terminal, with comment lines introducing each invocation. If the community sheets were declined at first run, this may instead report that no cheatsheet was found.

To see where cheat is actually looking, ask it for the configured paths:

```bash
cheat -d
```

The output lists the cheatpaths from conf.yml. This is the first thing to check when a sheet you expect is missing, because a sheet that exists on disk but sits outside every configured path is invisible to the tool.

Listing and filtering are the next step. To see everything available, or only what is tagged networking:

```bash
cheat -l
cheat -l -t networking
```

The brief variant, cheat -b, prints names and tags only, which is easier to scan once the corpus grows.

Creating your own sheet is a single flag. The README notes that -e opens the sheet for editing or creates it if it does not exist:

```bash
cheat -e tar
cheat -e foo/bar
```

Nested names work the same way, so foo/bar creates bar inside a foo subdirectory. Shell completions for bash, zsh, fish and powershell are generated on demand:

```bash
cheat --completion bash > ~/.local/share/bash-completion/completions/cheat
```

The README states that completions are dynamically generated and include cheatsheet names, tags and cheatpath names.

## Where cheat stops being the right tool

The largest limitation is content, not code. The executable ships nothing. If you install cheat and decline the community sheets, you have a viewer with an empty library, and the tool will not help you until you write files. That is a deliberate design choice, and it is also the reason cheat is a poor fit for anyone who wants a reference that works immediately after installation without a curation habit.

The second limitation is that cheatsheets are unvalidated prose. Nothing in the README suggests cheat parses or executes the commands in a sheet, so a stale sheet is indistinguishable from a correct one. A tar example that was right three years ago prints with the same confidence as one that is right today. Teams that treat sheets as shared infrastructure inherit that problem.

Third, the readonly copy-on-edit behaviour is helpful but surprising. If you edit a sheet on a read-only path, your change does not go where you might expect; it goes to a writeable directory, and the original stays untouched. That is the intended mechanism for avoiding merge conflicts, but it means the path you opened and the path that changed are different files. Anyone who assumes in-place editing will eventually be confused about which copy their teammates see.

Finally, this is not a search engine over a large corpus. The filtering flags compose well, but the README documents substring and regex matching over sheet contents, not ranked retrieval. For a few hundred personal sheets that is fine; for a documentation set you expect to grow into the thousands, the model starts to strain.

## cheat compared with tldr and plain man pages

The closest alternative in spirit is tldr, which also targets the remember-the-common-flags problem but inverts the content model. tldr clients ship against a shared, curated corpus that is the point of the project; the client is a thin renderer for pages maintained upstream. cheat does the opposite: the client is the project, and content lives in a separate repository that you may or may not install, with your own sheets taking priority. If you want an answer without writing anything, tldr's model fits better. If you want your own answers, including project-specific commands that no upstream corpus would ever carry, cheat's model fits better.

man pages are the other comparison, and the difference is editorial rather than technical. man documents everything a command can do, in the order the author chose. A cheatsheet documents the handful of invocations you personally keep forgetting, in your own words. cheat does not read man pages, so there is no generation step and no automatic freshness; the trade is that you get to decide what appears.

One practical middle ground the README supports: keep the community repository on a read-only cheatpath and your own directory on a writeable one. Community sheets stay current with a git pull, personal sheets stay yours, and an edit to a community sheet lands in your directory instead of the checkout.

## Maintenance cost, licensing and the upgrade path

The repository is not archived, and the last push was on 2026-05-19. The most recent release listed is 5.1.0 from 2026-02-16, following 5.0.0 and 4.7.1 earlier the same month. A major version bump in February means configuration or flag behaviour can shift between 4.x and 5.x, so pin a release rather than tracking master if you script against cheat's output.

The codebase is Go, module github.com/cheat/cheat, with dependencies on cobra for the CLI, Chroma for highlighting, yaml.v3 for configuration and go-git. The Makefile builds with -mod vendor, and the repository contains a vendor directory, so `make build` does not need network access for Go modules. The Makefile also exposes build-release, which cross-compiles for darwin, linux (386, amd64, arm variants), netbsd, openbsd, solaris and windows, and compresses the outputs. The Dockerfile is explicitly not part of that pipeline.

On licensing: the repository ships a LICENSE.txt and the project is MIT. MIT is permissive, so redistributing a modified binary is straightforward, but the cheatsheets you install from the community repository are a separate body of content with its own provenance, and nothing here tells you how that content is licensed. If you plan to ship cheat inside a product or mirror the sheet corpus internally, check the community repository's terms rather than assuming the MIT grant covers it. That is a factual gap, not a legal opinion.

## Conclusion

Adopt cheat if you spend time re-deriving tar, ssh or ffmpeg flags and you are willing to keep your own plain-text sheets in a directory you control. Skip it if you want a tool that ships a complete, pre-written reference, or if your team needs a shared documentation system with review and search across a large corpus; the project's own README points you at the separate cheatsheets repository for content, and cheat itself is only the viewer. Before committing, verify three things: run cheat -d to confirm which directories your build actually reads, open conf.yml and check that exactly one cheatpath has readonly: false so edits do not land in a checkout you later pull, and test cheat -e on a nested name such as foo/bar to confirm the transparent copy-to-writeable-path behaviour works with your layout. The last push to the repository was on 2026-05-19, so treat it as a stable tool rather than a fast-moving one, and pin a release binary instead of tracking master.

## FAQ

### Does cheat include any cheatsheets out of the box?

No. The README states that the cheat executable includes no cheatsheets, and that community-sourced cheatsheets are available in a separate repository. You are asked whether you want to install those community sheets the first time you run cheat.

### How do I list and filter the cheatsheets cheat can see?

Run cheat -l to list all available cheatsheets, or cheat -b for names and tags only. Filters compose, so cheat -l -t networking restricts the list to sheets tagged networking, and cheat -l -p personal restricts it to the personal cheatpath.

### What happens if I edit a cheatsheet on a read-only cheatpath?

The README says cheat will transparently copy that sheet to a writeable directory before opening it for editing, so the original on the read-only path is left untouched. This is the mechanism the project uses to prevent merge conflicts on upstream sheet repositories.

### Which shells can cheat generate completions for?

The README documents the --completion flag for bash, zsh, fish and powershell, with example redirections for each. Completions are dynamically generated and include cheatsheet names, tags and cheatpath names.

### How does cheat find project-local cheatsheets?

It searches for a .cheat directory in the current working directory and its ancestors, similar to how git locates .git directories. The nearest one found is temporarily added to the cheatpaths.

## Sources

- [cheat/cheat on GitHub](https://github.com/cheat/cheat)
- [Issues](https://github.com/cheat/cheat/issues)
- [License: MIT](https://github.com/cheat/cheat/blob/master/LICENSE)
- [README](https://github.com/cheat/cheat/blob/master/README.md)
- [Releases](https://github.com/cheat/cheat/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cheat-cheat