Guides

How to read command help (--help and man) — and find your version's flags in a minute

Illustration: the robot leafs through a thick open manual, a magnifier bookmark clipped to one page

The AI gave you a command, and the terminal answered unknown option. Or the other way round: the flag worked, just not the way it promised. Sound familiar? Usually it's the version. The model remembers the program one way, and you have a different one installed.

Good news: every program carries its manual inside it. And it's always about your version. Below is a step-by-step way to find the right flag in a minute instead of guessing.

Step 1. Ask the program itself: --help

Start with the fastest thing:

ls --help

Almost any program prints a short cheat sheet on --help: how to call it and what flags it has. If the text is long and scrolls away, add | less — then you can scroll with the arrows and quit with q.

If --help didn't work:

  1. Try -h. Old programs may not have the long flag.
  2. Read the error closely. We ran scp -h and got unknown option -- h. But right under the error, scp printed a usage: line with every flag. An error is help too.
  3. Programs with subcommands have help for each one: git commit -h, gh pr create --help, npm help install.

Step 2. Need more detail — open man

The --help cheat sheet tells you which flags exist. man (short for manual) explains what each one does:

man tar

A long page opens. The controls are easy:

  1. Space — next screen, b — back.
  2. /word and Enter — search the page. For example, /strip finds --strip-components.
  3. n — next search match.
  4. q — quit.

Every page has the same layout: NAME (one line on what it is), SYNOPSIS (how to call it), DESCRIPTION (all the flags), and often EXAMPLES at the very end. In a hurry? Search for /EXAMPLES straight away.

Git has a nice trick: git commit -h prints short help right in the terminal, while git commit --help opens the full man page.

Step 3. Decode the "how to call it" line

The scariest part of help is the usage line. Here's a piece of git commit -h:

usage: git commit [-a | --interactive | --patch] [-v] [-F <file> | -m <msg>]

It looks like a cipher, but there are only four rules:

  1. [ ] — optional. Write it or don't.
  2. | — "or". -F <file> | -m <msg> means: take the message from a file or type it in the command. Not both.
  3. < > or CAPITALS — a slot for your value. Replace <msg> with your message, FILE with a file name.
  4. ... — can repeat. ls [OPTION]... [FILE]... means: any number of flags and any number of files.

Now [-F <file> | -m <msg>] reads like English: "optionally give a message — as a file or as text". How flags themselves work, and why -ma breaks while -am doesn't, we covered in what is a command-line flag.

Step 4. When man is silent: built-in commands

Try man cd. You'll most likely get No manual entry for cd. That's not broken. cd isn't a separate program — it's a command built into the shell itself. You can check:

type cd
# cd is a shell builtin

For built-ins, the shell provides the help: help cd in bash. export, source, and alias behave the same way. What a shell is and how it differs from the window, we explained in what is the terminal.

Step 5. Give the AI your version's help

The strongest move. Instead of arguing with the model, show it the truth:

tar --version | head -1
tar --help > help.txt

And paste that into the chat along with the task.

Weak promptHow do I extract an archive without the extra folder?
Strong prompt

The model stops remembering and starts reading. The flags in its answer will come from exactly your version. This matters most for fresh AI tools: their CLIs change every month, while the model learned from old instructions.

What you end up with

After a couple of times it becomes a reflex: unfamiliar command → --help → the right flag via / in man → confirmed it exists in your version. A minute instead of half an hour on a forum. And fewer commands you run blind.

FAQ

What if man isn't installed?

Minimal Docker images and some servers ship without man pages. Then --help and the program's official docs in a browser still work.

Is there simpler help, with examples?

There's a program called tldr: for each command it shows the five to seven most common examples. Install it via npm, pip, or brew. It's an add-on to man, not a replacement.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →