Where we drilled
On 12 November 2026 we took the 30 most-starred GitHub repositories carrying the topic cli, as returned by the repository search API sorted by stars, and downloaded each default README through the README endpoint. Then we measured every file the same way, with a script, and checked the edge cases by hand.
The question was narrow on purpose. A visitor who wants to try a tool is looking for one thing: a line to paste into a terminal. So for each README we counted the words of prose that come before the first command a reader can copy to install or run the project. We also counted badges, pictures, total length and whether there is an Install heading.
- A word is any run of characters with a letter or digit, outside code blocks, HTML tags and image markup. Link text counts, link addresses do not.
- A command is a package manager or install line (
brew install,npm i,pipx install,cargo install,curl ... | shand the like) or a zero-install run line, inside a code block, inline code or a table cell. - A badge is an image from a badge service or a CI status image.
How deep the first command sits, repo by repo
25 of the 30 READMEs contain a command a visitor can paste. Across those 25, the median depth is 261 words: roughly one screen of reading on a laptop before the first line you can run. Six put it under 150 words. The deepest, sharkdp/fd, puts it after 2,466 words, below a long feature tour and benchmark section.
- codewhale-hq/Codewhale44
- sherlock-project/sherlock46
- google/zx60
- wagoodman/dive64
- obsidianmd/obsidian-skills77
- ajeetdsouza/zoxide133
- n8n-io/n8n169
- tldr-pages/tldr195
- Raphire/Win11Debloat202
- rtk-ai/rtk207
- herdrdev/herdr207
- Aider-AI/aider241
- google-gemini/gemini-cli261
- junegunn/fzf272
- morluto/rea305
- ohmyzsh/ohmyzsh325
- chubin/cheat.sh334
- spf13/cobra413
- OpenHands/OpenHands428
- tw93/Pake459
- sharkdp/bat816
- yt-dlp/yt-dlp822
- jesseduffield/lazygit1,442
- BurntSushi/ripgrep1,447
- sharkdp/fd2,466
The shallow end is mostly newer, single-purpose tools: codewhale-hq/Codewhale (44 words, then curl -fsSL ... | sh), sherlock-project/sherlock (46 words, a pipx install line in a table) and google/zx (60 words, then npm install zx). The deep end is older tools with long READMEs: BurntSushi/ripgrep and jesseduffield/lazygit both pass 1,400 words before their install section.
What the layers above the command hold
- 30 of 30repositories fill in the one-line description in the About box, so a visitor reads a pitch before the README starts.
- 4badges is the median. Seven READMEs carry none at all; yt-dlp/yt-dlp carries the most, 13.
- 28 of 30show at least one picture that is not a badge: a logo, a screenshot or a demo. Six embed an animated GIF, a video or a terminal recording we could identify by file type.
- 19 of 30have a heading with the word Install in it. 21 have a Quick start, Getting started, Usage or Example heading.
- 1,136words is the median length of the whole README. The shortest, google/zx, has 125; the longest, yt-dlp/yt-dlp, has 16,549 because it carries the full option reference.
The spread matters more than the medians. A 125-word README and a 16,549-word README both sit in the top 30. Length alone does not decide whether a project gets used; what a reader meets first is the part every one of them works on.
Five READMEs with no shell command at all
Five files never give a line to paste into a terminal. Each one sends the visitor somewhere else instead, and the choice is deliberate in every case:
- cli/cli links to an installation section and to separate docs for each platform.
- sxyazi/yazi links to its documentation site for installation and usage.
- jeecgboot/JeecgBoot, written in Chinese, links to a one-click install page on its help site.
- Panniantong/Agent-Reach, also in Chinese, gives a sentence to paste into an AI coding agent, which then reads an install file from the repository.
- charmbracelet/bubbletea is a Go library, so its README opens a tutorial with code to import rather than a tool to install.
Pointing to docs keeps one source of truth for many platforms. The cost is one more click for a visitor who only wanted to try it.
The full core box: all 30 READMEs
Stars, length and depth as read on 12 November 2026. Stars change daily; the README files can change on any commit.
| Repository | Stars | README words | Words before first command | Badges |
|---|---|---|---|---|
| morluto/rea | 454,431 | 2,729 | 305 | 9 |
| n8n-io/n8n | 210,290 | 438 | 169 | 0 |
| yt-dlp/yt-dlp | 207,185 | 16,549 | 822 | 13 |
| ohmyzsh/ohmyzsh | 190,582 | 2,505 | 325 | 6 |
| Panniantong/Agent-Reach | 111,264 | 365 | none | 8 |
| sherlock-project/sherlock | 110,462 | 151 | 46 | 1 |
| google-gemini/gemini-cli | 108,796 | 952 | 261 | 6 |
| OpenHands/OpenHands | 93,322 | 1,442 | 428 | 4 |
| rtk-ai/rtk | 86,338 | 1,885 | 207 | 8 |
| junegunn/fzf | 84,176 | 2,971 | 272 | 8 |
| jesseduffield/lazygit | 83,871 | 2,390 | 1,442 | 6 |
| BurntSushi/ripgrep | 69,912 | 2,358 | 1,447 | 3 |
| tldr-pages/tldr | 64,197 | 747 | 195 | 0 |
| tw93/Pake | 63,427 | 724 | 459 | 5 |
| Raphire/Win11Debloat | 62,446 | 1,114 | 202 | 3 |
| sharkdp/bat | 61,238 | 3,761 | 816 | 4 |
| wagoodman/dive | 54,723 | 1,157 | 64 | 5 |
| obsidianmd/obsidian-skills | 51,862 | 324 | 77 | 0 |
| herdrdev/herdr | 50,531 | 329 | 207 | 6 |
| Aider-AI/aider | 50,087 | 815 | 241 | 5 |
| jeecgboot/JeecgBoot | 48,442 | 777 | none | 8 |
| cli/cli | 46,984 | 518 | none | 0 |
| google/zx | 45,844 | 125 | 60 | 0 |
| charmbracelet/bubbletea | 45,716 | 1,275 | none | 2 |
| sharkdp/fd | 45,055 | 3,100 | 2,466 | 3 |
| spf13/cobra | 44,789 | 505 | 413 | 4 |
| sxyazi/yazi | 43,383 | 462 | none | 0 |
| chubin/cheat.sh | 41,857 | 2,826 | 334 | 12 |
| codewhale-hq/Codewhale | 41,178 | 1,764 | 44 | 4 |
| ajeetdsouza/zoxide | 40,578 | 1,338 | 133 | 0 |
What this sample cannot tell you
It shows what popular READMEs do, not what makes a visitor become a user. Nobody outside these projects can see how many readers scrolled, copied a command or installed. Stars also build up over years, so a README rewritten last month gets credit for stars earned by an older version.
The sample is one topic and one moment: 30 repositories tagged cli, read on one day. Libraries, apps and frameworks may look different. Use the numbers as a reference point when you edit your own file, and check them against GitHub's own advice on READMEs, which lists what a README usually answers: what the project does, why it is useful, how to start, where to get help and who maintains it.
If your first command sits deeper than about 260 words, you are deeper than half of this sample. Moving one install line up is the cheapest edit you can make.



