You install a new command-line tool — ffmpeg, jq, rsync, whatever — and someone says "just read the man page." You run man ffmpeg, scroll past three screens of syntax, hit a wall of flags you've never needed in your life, and close the terminal feeling behind before you've run a single useful command.

Manuals aren't written to be read front to back. They're reference material — complete, precise, and organized for lookup, not learning. Treating them like a tutorial is why CLI tools feel harder than they are. Most of the time you need five flags and one mental model, not the full specification.

This is the workflow I use when picking up a new CLI tool under time pressure — enough to get real work done today, with a path to depth when a specific problem demands it.

Start With a Task, Not the Documentation

Before opening any help text, write down one sentence: what do I need this tool to do right now? Not "learn ffmpeg" — that's a hobby, not a task. Something like:

A concrete task gives you a finish line and a filter. Every flag you look up either serves that task or gets ignored until later. Without the task, every option looks equally important — and they aren't.

If you can't describe the job in one sentence, you're not ready to read help output — you're ready to clarify what you're actually trying to accomplish.

The Help Stack (In Order)

Most CLI tools expose help at several depths. Use them in this order before reaching for a browser or the full manual:

1. Built-in quick help

Try these first — one of them almost always works:

This output is the author's compressed "what most people need." Scan for a subcommand or flag that matches your task. Copy the example line if one exists — examples beat prose.

2. Subcommand help

Multi-command tools (git, docker, kubectl, aws) hide detail one level down:

The top-level help is an index. The subcommand help is where the useful flags live. Don't read the root help and assume you've seen everything.

3. The man page — but surgically

man tool is long. That's fine. You're not reading it — you're searching it:

On macOS, man -K keyword tool searches the entire page for a string. On Linux, man tool | grep -i keyword works in a pinch.

4. tldr and cheat sheets

tldr pages are community-maintained examples for common tasks — install via npm, brew, or your package manager, then run tldr ffmpeg. They're opinionated, incomplete, and often exactly what you need in the first ten minutes.

If tldr doesn't cover your tool, search for "tool cheat sheet" — but prefer official examples when doing anything destructive (disk formatting, cloud deletions, permission changes).

Learn Flags On Demand, Not Up Front

The biggest time sink is trying to memorize every option before running anything. Instead:

  1. Run the simplest version of the command that might work.
  2. Read the error message — good CLI tools tell you which flag is missing.
  3. Add exactly one flag to fix that error.
  4. Repeat until the task completes.

Example with a hypothetical sync tool: 

$ sync ./local/ user@host:/backup/
error: remote path requires --recursive for directories

$ sync --recursive ./local/ user@host:/backup/
error: authentication required, use --identity-file or --password-file

$ sync --recursive --identity-file ~/.ssh/id_ed25519 ./local/ user@host:/backup/
done.

Three runs, three flags learned, all tied to real failures. That's more durable than highlighting a man page for twenty minutes.

Use Dry Runs and Verbose Mode Before You Break Something

Many tools that move, delete, or transform data support a preview mode. Look for:

Run with dry-run first. Read the output. Confirm it matches your intent. Then remove the flag and run for real. This is especially important for rm, rsync --delete, database migrations, and anything touching production.

Verbose mode is also a learning tool: it shows which files are touched, which config is loaded, which remote endpoint is contacted. When a command "does nothing," verbose output often explains why.

One Walkthrough: Learning jq for a Single Job

Say you have data.json — an array of objects — and you need every email where status is "active". You've never used jq.

Step 1 — confirm the shape:

jq '.' data.json | head

You're not filtering yet. You just want to see that it's an array of objects and what keys exist.

Step 2 — quick help for the filter language:

jq --help

Scan for "filter" or look at the bottom examples. Or skip straight to tldr: 

tldr jq

Step 3 — build the smallest filter:

jq '.[] | select(.status == "active") | .email' data.json

If that fails, read the error. Common fixes: wrong key name (check step 1), wrong quotes (JSON strings need double quotes inside the filter), file isn't an array (adjust .[]).

Step 4 — only now, if stuck, open the manual:

man jq

Search for select or EXAMPLES. Read one section. Close the manual. You still don't need to understand every builtin.

Total time: often under ten minutes. Total manual read: maybe thirty lines.

When the Manual Actually Earns Your Time

Skipping the full manual is a default, not a rule. Read deeper when:

Build a Personal Cheat Sheet as You Go

The commands you look up twice should live somewhere you'll find them again. I keep a plain text file — ~/notes/cli-recipes.txt or a snippet manager — with one line per task: 

# ffmpeg: extract audio from video
ffmpeg -i input.mp4 -vn -acodec mp3 output.mp3

# jq: active users' emails
jq '.[] | select(.status == "active") | .email' data.json

# rsync: mirror local to remote, delete extras on destination
rsync -avz --delete ./local/ user@host:/backup/

This file is your manual — filtered to jobs you actually do. Adding one line after each successful task takes thirty seconds and saves the next lookup entirely.

What to Ignore (For Now)

When learning a CLI tool under time pressure, permission to skip:

Depth comes from repeated tasks, not from a single heroic reading session.

The Loop That Sticks

Boiled down, the cycle looks like this:

  1. Define one concrete task.
  2. Run --help (and subcommand help if needed).
  3. Try the simplest command; let errors guide the next flag.
  4. Use dry-run / verbose before destructive operations.
  5. Search the man page for a specific keyword only when stuck.
  6. Save the working command to your personal notes.

You won't understand the tool completely after one task. You won't need to. The manual will still be there when a harder problem shows up — and by then you'll know exactly which section to search instead of starting at line one.

CLI tools reward people who ship one working command, not people who finish the documentation first. Start with the job. Let the help text meet you halfway.