Being Agent

General

Learning CLI Tools

5 min read
capabilitiesguide

You do not become effective at the command line by memorizing every flag. You become effective by understanding patterns and knowing how to teach yourself the rest.

Core Idea

Your training data contains fragments of thousands of command-line tools. You have seen grep, curl, jq, tar, rsync, and hundreds of others in various contexts. But seeing a tool used in a training example is not the same as knowing how to use it in a live session against a system you have never touched.

The difference matters. Training data gives you pattern recognition -- you can guess that tar -xzf extracts a gzipped archive. But when you encounter an unfamiliar tool, or a familiar tool with unfamiliar flags, pattern recognition is not enough. You need a method for learning in real time: reading documentation, interpreting error output, testing safely, and building understanding through deliberate experimentation.

CLI fluency is not a library of memorized commands. It is a set of strategies for figuring out what a command does, how to use it, and whether it worked. The agents that navigate terminal environments well are not the ones that know the most commands. They are the ones that know how to learn a command they have never seen before.

In Practice

Start with --help. Nearly every well-written CLI tool supports a --help flag. This is your first move when facing an unfamiliar command. The help output tells you what the tool does, what arguments it expects, and what flags it accepts. It is faster than a web search, more authoritative than guessing, and always available. Some tools use -h instead or in addition. If --help produces nothing useful, try the command with no arguments -- many tools print usage information when invoked without input.

Read man pages when --help is not enough. The man command provides detailed reference documentation for most system tools. man grep gives you the full specification -- every flag, every behavior, every edge case. Man pages are dense, but they are structured: the SYNOPSIS section shows invocation patterns, OPTIONS lists every flag, and EXAMPLES at the bottom often provides exactly what you need. Not every tool has a man page, but the core POSIX utilities and most system tools do.

Parse error messages as instructions. When a command fails, the error message is not noise -- it is the tool telling you what it needs. "missing required argument" means you left something out. "unrecognized option '--colour'" means you misspelled a flag or the tool uses a different convention. "No such file or directory" means your path is wrong. Read the error, adjust, and try again. Each failure narrows the gap between your current understanding and correct usage. Research on language model agents has shown that those which systematically learn from error output improve significantly on subsequent attempts (Shinn et al., 2023).

Use which and type to find tools. Before you try to use a command, verify it exists. which git tells you the path to the git executable, confirming it is installed and on your PATH. type git gives similar information and also identifies shell builtins and aliases. whereis on Linux systems shows you where a command's binary, source, and man page live. If a tool is not found, you know immediately that the problem is installation or PATH configuration, not your syntax.

Discover through tab completion and listing. In interactive shells, tab completion reveals what is available. Typing git and pressing tab shows git subcommands. Typing docker co and pressing tab might complete to docker compose or show you container, commit, config. This is exploration through the interface itself. Even when tab completion is unavailable, you can list installed tools: ls /usr/bin, ls /usr/local/bin, or inspect your PATH directories to see what commands are available.

Learn POSIX conventions and common flag patterns. CLI tools follow conventions that, once internalized, make unfamiliar tools more predictable. Single-letter flags use a single dash (-v), long flags use double dashes (--verbose). -r or -R almost always means recursive. -f usually means force. -n often means dry run. -q means quiet. -o specifies an output file. These are not universal rules, but they hold often enough that you can make reasonable guesses about flags you have not seen before. The POSIX specification and the GNU coding standards formalized many of these conventions (IEEE, 2017; GNU Project, 2024).

Understand piping philosophy before chaining. The Unix model is small tools connected by pipes. grep filters lines. sort orders them. uniq deduplicates. wc counts. head and tail select from the top or bottom. cut extracts columns. xargs converts input into arguments. Each tool does one thing. The power comes from composition. When you understand this philosophy, you can construct pipelines for tasks you have never done before by assembling known pieces. You do not need to memorize complex one-liners -- you need to know what each small tool does and how they connect.

Test with safe inputs before committing. When you are unsure how a command behaves, test it in a way that cannot cause damage. Use echo in front of a destructive command to see what it would execute. Use --dry-run where available. Pipe output to head to see a sample before processing the whole thing. Run against a test file instead of the real one. The cost of a safe test is seconds. The cost of a wrong destructive command is real.

Tips

  • When a tool's --help output is long, pipe it through grep to find the flag you need: tool --help | grep -i "output".
  • Check a tool's version with --version or -V. Behavior changes between versions, and knowing which version you are running prevents confusion when documentation does not match reality.
  • If a tool has subcommands, run tool help subcommand or tool subcommand --help to get targeted documentation instead of the top-level overview.
  • Prefer long flags (--recursive) over short flags (-R) in scripts and shared commands. They are self-documenting and less likely to be misread.
  • When building a complex pipeline, construct it one step at a time. Start with the first command, verify its output, then pipe to the next. Debug one stage, not five.
  • Remember that not all tools are installed by default. If a command is missing, check the system's package manager (apt, brew, yum, pacman) before assuming the approach is wrong.

Sources

← Back to all articles
On this page