cheatree

A terminal-first cheatsheet system with tree-based YAML structure. It supports vim binding and it is ai-native (ie. there are commands available to make it easy for claude-code/other ai agents to manage cheatsheets)

TUI

CLI

Installation

cargo install cheatree

From source

cargo install --path .

Quick Start

# Create your first cheatsheet
cheatree new git

# List all cheatsheets
cheatree list

# Open the TUI viewer
cheatree open git
# Or simply:
cheatree git

# Get content non-interactively
cheatree get git --path "Basics.clone"
cheatree get git --query "branch"
cheatree get git --format yaml

Usage

Commands

Command	Description
cheatree list	List all available cheatsheets
cheatree new <name>	Create a new cheatsheet
cheatree open [<name>]	Open TUI (interactive selector if no name)
cheatree <name>	Shorthand for open <name>
cheatree get <name>	Print cheatsheet content
cheatree edit <name>	Open in $EDITOR
cheatree where	Show data directories
cheatree import <path>	Import a YAML file
cheatree doctor	Validate all cheatsheets
cheatree delete <name>	Delete a cheatsheet
cheatree set <name> -p <path>	Add/update entry (AI-friendly)
cheatree rm <name> -p <path>	Remove entry at path
cheatree path <name>	Print raw YAML file path

TUI Keybindings

Key	Action
j / ↓	Move down
k / ↑	Move up
Enter / Space / l	Expand/collapse section
h	Collapse current section
g	Go to top
G	Go to bottom
/	Search
f	Filter
y	Copy command to clipboard
e	Edit cheatsheet in $EDITOR
r	Reload cheatsheet
o	Expand all sections
O	Collapse all sections
?	Toggle help
q / Esc	Quit / Cancel

CLI Get Options

# Get entire cheatsheet
cheatree get git

# Get by path (dot notation)
cheatree get git --path "Branches.create"

# Search
cheatree get git --query "merge"

# Filter by header
cheatree get git --header "Remote"

# Output formats
cheatree get git --format text   # default
cheatree get git --format yaml
cheatree get git --format json

AI/Automation Commands

These commands are designed for AI agents and scripts that can't use the TUI:

# Add or update an entry
cheatree set git -p "Branches.delete" --cmd "git branch -d <branch>" --desc "Delete a local branch"

# Add with examples
cheatree set git -p "Branches.delete" --cmd "git branch -d <branch>" -e "git branch -d feature-123"

# Read entry from stdin as YAML
echo 'desc: "Delete branch"
cmd: "git branch -d <name>"
examples:
  - "git branch -d feature-123"' | cheatree set git -p "Branches.delete" --stdin

# Remove an entry
cheatree rm git -p "Branches.delete"

# Get the raw file path (for direct editing)
cheatree path git
# Output: /home/user/.local/share/cheatree/cheatsheets/git.yaml

# View in YAML format (for parsing)
cheatree get git --format yaml

# View specific path
cheatree get git --path "Branches" --format yaml

AI Workflow Example

# 1. Check if cheatsheet exists
cheatree list

# 2. View current content
cheatree get docker --format yaml

# 3. Add new entries
cheatree set docker -p "Images.build" --cmd "docker build -t <name> ." --desc "Build an image"
cheatree set docker -p "Images.list" --cmd "docker images" --desc "List all images"

# 4. Verify
cheatree get docker --path "Images" --format yaml

YAML Schema

Cheatsheets are YAML files with this structure:

version: 1
meta:
  title: "Cheatsheet Title"
  description: "Description of the cheatsheet"
  tags: ["tag1", "tag2"]
tree:
  SectionName:
    SubSection:
      leaf_key:
        desc: "Description of what this does"
        cmd: "the command or shortcut"
        examples:
          - "example usage 1"
          - "example usage 2"
        links:
          - "https://docs.example.com"
        platform: "linux"  # optional: linux, macos, all
        shell: "bash"      # optional: bash, zsh, fish

Node Types

1. Section: A mapping containing other nodes (sections or leaves)
2. Leaf: An entry with desc, cmd, examples, etc.

Path Selectors

Use dot-notation to select specific paths:

# Simple path
cheatree get git --path "Branches.create"

# Path with spaces (use quotes)
cheatree get mysheet --path 'Section."Sub Section".item'

File Locations

cheatree follows the XDG Base Directory Specification:

Directory	Linux	macOS
Data	~/.local/share/cheatree/	~/Library/Application Support/com.cheatree.cheatree/
Config	~/.config/cheatree/	~/Library/Application Support/com.cheatree.cheatree/
Cheatsheets	{data}/cheatsheets/*.yaml	{data}/cheatsheets/*.yaml

Run cheatree where to see your actual directories.

Configuration

Create config.toml in your config directory:

# Optional: override editor
editor = "nvim"

# Default output format for `get` command
default_format = "text"

[tui]
# Show line numbers in detail view
show_line_numbers = false

# Use vim-style keybindings (j/k navigation)
vim_keys = true

# Expand all sections by default
expand_all = false

# Tree indent width
indent_width = 2

Sample Cheatsheets

The examples/ directory contains sample cheatsheets:

• yazi.yaml - Yazi file manager
• git.yaml - Git version control
• vim.yaml - Vim/Neovim editor

Import them with:

cheatree import examples/git.yaml
cheatree import examples/vim.yaml
cheatree import examples/yazi.yaml

Development

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run -- list

# Build release
cargo build --release

License

MIT