WebCLI Spec

Version

0.1-draft

Published

March 13, 2026

Author

@chandler212

Repository

github.com/webclihq/spec

License

CC BY 4.0

Status

Draft — open for community input

What is WebCLI? ¶

When a developer asks an LLM to write a shell script using git, curl, or docker, the model gets it right: flags, subcommands, output format and all. It doesn't need documentation in the prompt. It already knows.

That's not magic. It's saturation. These tools have appeared billions of times in pre-2024 training data: in READMEs, Stack Overflow answers, blog posts, CI configs, and shell scripts. The patterns are baked in.

WebCLI is a specification for building new CLIs that match those saturated patterns closely enough that LLMs already "know" how your tool works from day one, without any training, documentation injection, or special prompting.

The 10 Canonical CLIs ¶

The WebCLI spec is derived from analyzing the help output and thousands of example invocations of the ten CLIs most heavily represented in LLM pre-training corpora. These tools define the pattern language that models internalize.

Research & Evidence ¶

The WebCLI spec is grounded in empirical analysis, not opinion. For each of the 10 canonical CLIs, two documents were produced: the complete help output as emitted by the tool, and 100 real-world example invocations covering basic to advanced usage. All 20 documents were then analyzed to surface the flag conventions, subcommand structures, output contracts, and verb vocabularies that appear most consistently, and therefore carry the highest density in LLM pre-training corpora.

The synthesis of that analysis is cli_design_patterns.md, which serves as the primary source of truth for the spec. Every design rule on this page can be traced back to a specific pattern observed across multiple tools in the evidence below.

Core Principles ¶

Five design rules distilled from the 10 canonical CLIs. A conformant CLI follows all five.

1. Help Output ¶

Help text must be emitted on --help (and -h) to stdout, and follow a consistent structure that models have seen millions of times:

Usage: TOOL [OPTIONS] COMMAND [ARGS]...

<one-line description>

Options:
  -f, --flag   Description of flag      [default: value]
  -h, --help   Show this message and exit

Commands:
  verb    Short description of verb

Models parse this structure implicitly. Deviate from it and the LLM will hallucinate flags that don't exist.

2. Flag Conventions ¶

Every flag must have a long form. Short forms are optional but follow POSIX single-character conventions when present.

• Boolean flags: --verbose / --no-verbose pair
• Value flags: --output FILE or --output=FILE (both must work)
• Short aliases: -v for --verbose, -o for --output
• Stacking short flags: -xvf must be equivalent to -x -v -f

3. Subcommand Structure ¶

Use verb subcommands for actions (init, build, deploy, list, get, set, delete). Prefer flat over nested. If nesting is necessary, follow the docker object-verb pattern: tool resource action.

$ tool init          # verb
$ tool config get    # object-verb (docker-style)
$ tool config set KEY=VALUE

4. Exit Codes ¶

Exit codes must be consistent and documented. Models infer script logic from exit code conventions:

5. stdout / stderr ¶

Actionable output goes to stdout. Logs, warnings, and progress go to stderr. This is the invariant that makes pipelines work, and the one LLMs assume without being told.

$ tool build 2>/dev/null | jq .   # works only if stdout is clean JSON

Specification ¶

The following design rules are derived directly from cross-analysis of the ten canonical CLIs. Each rule identifies the pattern that appears most consistently across the training corpus, and therefore carries the highest confidence weight in LLM representations.

§1 Universal Flags ¶

These flags appear across all or nearly all of the ten canonical CLIs. LLMs will predict them with near-certainty.

§2 Subcommand Structure ¶

Pattern A: <tool> <verb> <noun>: dominant in high-level tools (git, docker, npm, pip)

git commit -m "message"
docker run -d nginx
npm install lodash
pip install requests

Verbs are simple English: run, build, push, pull, install, uninstall, list, show, create, delete, start, stop, logs. Nouns are resource names: container, image, network, volume, package, branch, tag.

Pattern B: <tool> [flags] <target>: dominant in low-level/Unix tools (curl, grep, ssh, wget, make)

curl -X POST -H "Content-Type: application/json" https://api.example.com
grep -rn "TODO" ./src
ssh -p 2222 user@hostname
wget -O file.tar.gz https://example.com/

No subcommands: the primary action is implied by the tool. Options modify behavior; positional arguments are targets.

§3 Help Access Patterns ¶

§4 Output Conventions ¶

§5 JSON Output ¶

Four of the ten tools support structured JSON output, and this pattern is rapidly converging:

Emerging standard: --output json or --format json.

§6 Verb Vocabulary ¶

The most LLM-saturated action verbs, ranked by frequency across all ten tools' help output and examples:

§7 Flag Naming Conventions ¶

Short flags (-x): single character, preceded by single dash. Can be combined: -rf, -vvv, -aux. Used for frequently-typed, well-known flags.

Long flags (--flag-name): lowercase with hyphens (not underscores), preceded by double dash. Can take a value: --output=file.json or --output file.json.

Value separator: Both --flag=value and --flag value are used across the ten tools. Supporting both is safest.

Boolean flags:

• Positive: --verbose, --force, --recursive
• Negative: --no-color, --no-cache, --no-verify
• Pattern --no-<flag> is used by curl, wget, docker, npm

§8 Positional Argument Conventions ¶

Options come before positional arguments. Multiple positional args are common (files, URLs, targets).

§9 Configuration Layering ¶

All ten tools support configuration at multiple layers, in priority order (highest to lowest):

1. Command-line flags — all 10 tools
2. Environment variables — curl (CURL_CA_BUNDLE), docker (DOCKER_HOST), npm (NPM_TOKEN), git (GIT_DIR)
3. Per-project config file — git (.git/config), npm (.npmrc), make (Makefile)
4. User config file — git (~/.gitconfig), npm (~/.npmrc), pip (~/.config/pip/pip.conf), curl (~/.curlrc)
5. System config file — ssh (/etc/ssh/ssh_config), git (/etc/gitconfig)

§10 Piping & Composability ¶

The most frequently seen piping patterns in training data:

# Pipe to jq (JSON output)
docker inspect container | jq '.NetworkSettings.IPAddress'
npm list --json | jq '.dependencies | keys'

# Pipe to grep (filter output)
docker ps | grep "nginx"
git log --oneline | grep "fix:"
pip list | grep "requests"

# Pipe to xargs (act on output)
docker ps -q | xargs docker stop
git diff --name-only | xargs grep "TODO"

# Silent with exit status check
curl -sf https://api.example.com/health && echo "OK"
make -q && echo "Up to date"

# Redirect output to file
git log > commits.txt
npm list > packages.txt

§11 Summary: Recommended Conventions ¶

A conformant LLM-fluent CLI applies all of the following:

Why It Works ¶

LLMs don't learn tools from documentation at inference time. They learn from the statistical distribution of patterns in training data. When your CLI matches the patterns of git, curl, and docker, the model's internal representations transfer directly.

This is the same principle as transfer learning in neural networks, except the "model" is already trained, and you're designing your tool to land in a high-density region of its learned pattern space.

A conformant WebCLI tool will be correctly invoked, piped, and scripted by an LLM with no documentation in context: just the tool name and a task description. Non-conformant CLIs require documentation injection, fine-tuning, or repeated correction.

Get Involved ¶

WebCLI is an open specification. Contributions, corrections, and RFCs are welcome.

• GitHub: github.com/webclihq/spec — spec source, issues, and discussions
• Propose an RFC: Open an issue with the [RFC] prefix to propose a spec change
• Conformance testing: A reference CLI linter (webcli-lint) is planned for v0.2