How to Describe a CLI to AI Agents

An agent can understand what a command should do and still get its syntax wrong. In linear-cli, my command-line tool for Linear, the issue tracker, “close issue POL-5” could become linear issue POL-5 close instead of linear issue close POL-5.

The missing information was the command language: which tokens are valid, how they nest, and where arguments belong. A description for an agent should make those choices explicit.

Show the accepted syntax

“Issues can be listed, viewed, or closed” names capabilities but leaves their syntax unspecified. A command synopsis supplies the missing structure:

linear issue close ID

Here, linear issue close is literal command text and ID is the issue identifier. Substituting POL-5 gives the accepted command without guessing the argument order.

Extend that description to cover the available subcommands, required arguments, optional flags, and allowed values. Explain what placeholders mean; a token such as Text also needs shell quoting when its value contains spaces. Examples make a rule concrete, but the description needs to expose the choices that change between commands.

Express shared structure with a grammar

When several commands share a structure, a grammar can express it once. Extended Backus–Naur Form (EBNF) provides notation for alternatives, sequences, and optional parts.

A short EBNF excerpt shows the idea.¹ Quoted words are literal arguments; ::= defines a rule, | separates alternatives, parentheses group them, and ? marks an optional part. ID, Key, and Text stand for an issue identifier, team key, and text argument.

Command ::= "linear" "issue" (
    ("close" | "start" | "reopen") ID
  | "comment" ID Text
  | "create" "--team" Key "--title" Text ("--priority" Priority)?
)
Priority ::= "urgent" | "high" | "medium" | "low" | "none"

The create branch produces commands such as:

linear issue create --team POL --title "Fix login" --priority high

Here, high is one allowed Priority; the entire --priority high pair is optional. Shell quoting keeps Fix login together as one title argument.

A synopsis can state each command directly; a grammar can factor out their common structure. The useful property is explicit syntax, whichever notation makes that syntax easiest to follow.

Check the description against real tasks

I tested this distinction with 18 task requests in one prompt, asking the model to predict commands without executing them. I kept the CLI and tasks fixed and varied the description. My February 2026 notes preserve these approximate results; the underlying outputs no longer survive.² Token counts measure the supplied descriptions.

On this task set, the full synopsis and grammar both reached roughly 100% correct predictions. Both made the syntax explicit; the grammar did so with roughly half as many description tokens.

Fix missing information before accommodating guesses

Before that comparison, I had tried to accommodate wrong commands through better help, error messages, and synonyms, testing the changes against an execution-scenario harness.

I also added a preprocessor that rearranged the arguments:

linear issue POL-5 close → linear issue close POL-5

That made a guessed argument order another rule the parser had to maintain. The description experiment gave me a reason to revisit the workaround.

In commit 792557c, I removed the ID-first preprocessor and its supporting code. Ordinary synonyms such as done for close moved into the parser framework's native alias mechanism. An error hint still showed the canonical order when an identifier appeared first.

When an agent misuses a CLI, check what its description leaves implicit. Show the accepted command language, test it on representative tasks, and use the remaining failures to decide what the tool itself needs to change.