The Problem

Learning Linux commands from scattered blog posts or man pages is slow and unstructured. This repo packages 101+ commands into a single, navigable reference with practical examples, and adds a CLI to search and display them from the terminal.

What This Does

The repository is a fork of bobbyiliev/101-linux-commands (1,091 stars upstream). The bulk is content: 174 Markdown files in ebook/en/content/, one per command (e.g. 001-the-ls-command.md, 107-the-grep-command.md), plus HTML/CSS assets for an online version. A Python CLI in cli/ lets you search and read those commands without opening the browser.

The CLI is built with Typer. cli/cli.py defines the main entry point and a CustomTyper class; subcommands live in cli/commands/ (search.py, show.py, list.py, build.py, hello.py, version.py). Command metadata is generated from the Markdown into cli/data/commands.json by cli/scripts/generate_command_index.py.

How It Is Wired

Execution starts at main in cli/cli.py:54. It reaches 11 functions. The search command (cli/commands/search.py) is the workhorse: search calls _get_available_commands and _search_commands, and is called from 4 places. The _extract_* functions in generate_command_index.py parse each Markdown file into title, command name, description, usage, and example — this is the only path that touches the filesystem (via path.read_text). debug in cli/states/global_state.py is called from 6 places, so it's the widest blast radius for any change.

There are 13 internal modules with zero import edges between them — no hub, no cycles. The module graph is flat; the coupling is through the commands.json data file, not code imports. There are 22 resolved call edges, all within the CLI.

How To Use It

The CLI uses pyproject.toml with a uv.lock present, so uv is the package manager:

git clone https://github.com/moses-y/101-linux-commands
cd 101-linux-commands/cli
uv sync
uv run cli --help

The cli/README.md documents the subcommands. No environment variables are required. The ebook itself is plain Markdown — read it directly or open index.html for the web version.

Real-World Use

A sysadmin onboarding a junior engineer points them at this repo instead of a wall of bookmarks. The CLI makes it a habit:

uv run cli search grep
uv run cli show awk

For the maintainer, cli/scripts/generate_command_index.py regenerates commands.json from the Markdown, so adding a new command chapter automatically updates the CLI's search index.

Code Health & Issues

Static analysis (measured, not opinion) found 4 medium findings: deep nesting in ebook/en/ibis.php (indentation depth 6), and broad except clauses in cli/commands/search.py, cli/commands/show.py, and cli/scripts/generate_command_index.py that swallow errors indiscriminately.

The SDLC audit adds three high-severity items: third-party GitHub Actions pinned to tags not commit SHAs (.github/workflows), no lockfile beside composer.json, and a workflow (ibis.yml) that pushes directly to the default branch. Medium: no Dependabot, no dependency vulnerability scan in CI, persist-credentials not disabled on checkout. Low: no timeout-minutes on workflow jobs. Tests exist (cli/tests/) and CI runs GitHub Actions.

The Bottom Line

Solid educational content with a genuinely useful search CLI. The code is small and flat — easy to maintain. The CI hygiene needs attention before this is production-grade, but for a learning resource, the content quality is what matters, and it's good.