tldr / cheat / navi：再也不读 man 全文

起因

man tar 输出 300 行，我只想知道"怎么解压一个 .tar.gz"。
man 是参考手册，新人 / 偶尔用户需要的是"3 个常用例子"。

tldr 项目（"Too Long; Didn't Read"）是社区维护的 CLI 命令速查，
每个命令给 5-10 个常见用法。

tldr

# 装
brew install tldr             # macOS
sudo apt install tldr         # Debian/Ubuntu
npm i -g tldr                  # 跨平台

# 或者 Rust 实现（快得多）
cargo install tealdeur
alias tldr=tldr               # rust 二进制叫 tldr

tldr tar

输出：

tar

Archiving utility.

- Create an archive from files:
    tar cf {{target.tar}} {{file1 file2 file3}}

- Create a gzipped archive:
    tar czf {{target.tar.gz}} {{file1 file2 file3}}

- Extract a gzipped archive in the current directory:
    tar xzf {{source.tar.gz}}

- Extract an archive into a target directory:
    tar xf {{source.tar}} -C {{directory}}

- List the contents of an archive:
    tar tvf {{source.tar}}

5 个例子覆盖 90% 用法。man tar 几百行的实际有用部分浓缩成 30 秒
能读完。

更新 cache

tldr --update

定期跑更新到最新版社区贡献。

离线工作

第一次跑 tldr --update 后所有 cheat sheet 缓存到本地（~30 MB），
之后无网络也能查。

不同 OS 的命令变体

tldr 自动检测你的平台显示对应版本：

tldr -p linux ls
tldr -p osx ls
tldr -p windows dir

Linux 上 find vs macOS BSD 版 find 语法不同，tldr 给你正确的。

cheat

类似 tldr 但更"自己加"友好：

# 装（Go 二进制）
go install github.com/cheat/cheat/cmd/cheat@latest

cheat tar
# 显示 tar 的 cheatsheet

cheat -e tar
# 用编辑器修改本地 tar cheatsheet（写自己常用的）

cheat -l
# 列所有 cheatsheets

~/.config/cheat/cheatsheets/community/ 是社区版本；
~/.config/cheat/cheatsheets/personal/ 是你自己加的（优先显示）。

适合"团队内部的命令速查"——给项目特定的命令写 cheat。

navi：interactive cheatsheet + 直接执行

brew install navi
cargo install navi

navi
# TUI 弹出，浏览所有 cheats，选中后回车直接执行

cheat 文件格式：

% docker

# stop all containers
docker stop $(docker ps -aq)

# remove all stopped containers
docker rm $(docker ps -aq)

# list images sorted by size
docker images --format '{{.Repository}}:{{.Tag}} {{.Size}}' | sort -k 2 -h

navi 会让你 fuzzy 搜（"docker stop all"），找到后直接执行。
对"我知道有这条命令但记不清完整"特别适合。

参数化命令：

% find

# find files by name (case insensitive)
find <dir> -iname "*<pattern>*"

navi 选中后弹小框让你填 <dir> 和 <pattern>，然后执行。

同步团队 cheat

navi --finder fzf --query 'docker'
navi --tldr 'tar'      # 直接调用 tldr
navi repo browse        # 浏览社区 cheat 仓库
navi repo add <git-url> # 加自定义 repo

公司内部 cheat 仓库 + navi repo add [email protected]/cheats.git →
全员共享团队最佳实践。

bro pages（命令请求帮助 + 评分）

# 装（不再积极维护，但仍可用）
gem install bropages

bro tar
# 显示社区贡献的 examples，按点赞排序

bro thanks   # 给当前显示的 example 点赞
bro add tar  # 自己贡献一个 example

社区驱动 vs tldr 的"官方维护"差异：
bro 更草根，tldr 更整洁。

自己装"代码 snippet"

我个人的 ~/notes/cli.md：

## ssh 隧道

# Local port -> remote service through bastion
ssh -L 8080:internal-host:80 -N bastion

# Reverse tunnel: expose local port to remote
ssh -R 9000:localhost:9000 -N remote

## ffmpeg

# extract audio
ffmpeg -i in.mp4 -vn -acodec copy out.aac

# convert to mp3
ffmpeg -i in.wav -codec:a libmp3lame -b:a 192k out.mp3

# trim by time
ffmpeg -i in.mp4 -ss 00:01:30 -t 00:00:30 -c copy out.mp4

# add subtitle
ffmpeg -i in.mp4 -vf subtitles=in.srt out.mp4

配合 fzf 让自己的笔记可搜：

mynote() {
  grep -E '^#' ~/notes/cli.md | fzf | xargs -I {} grep -A 5 '^{}' ~/notes/cli.md
}

打 mynote → fzf 出来所有标题 → 选一个看内容。

与 ChatGPT / Claude 的关系

LLM 也能"我想做 X 命令怎么写"。优劣：

LLM：自由表达、不限范围；可能编造（小心 hallucination）
tldr / cheat：人工验证、可靠；范围限于已收录

我现在混用：

先 tldr cmd → 如果想要的功能在 5 个例子里直接用
否则问 LLM → 验证后加进自己的 ~/notes/cli.md

效果

不再 man tar / man find 滚屏几分钟找 example
团队"上次那个 ffmpeg 命令是啥来着" 类问题 → 自己 cheat 速查
新人 onboarding 速查内部命令大幅简化（navi + 团队 cheat repo）

踩过的坑

tldr 例子里 <placeholder> 别照抄：{{file}} 是占位符，
替换成真值再跑。
cheat 跨用户同步：~/.config/cheat/cheatsheets/personal/
进自己 dotfiles repo + symlink，多机器同步。
navi 选 cheat 后误执行：危险命令（rm -rf）navi 默认会先填参数
但仍会执行。一行 cheat 写法注意防滑指。
bropages 维护停了：不推荐新装，迁 tldr / navi。
tldr 命令冲突：有 Node / Python / Rust / shell 多个实现。
PATH 里只留一个，按需 alias。