Command-line interface (CLI)

A CLI has three visible parts: the utility name, the options and arguments passed to it, and the results it returns — text on standard output and standard error plus an exit status, where zero conventionally signals success and any non-zero value signals an error. On POSIX-like systems the expected spelling of options (single-letter options after a hyphen, -- as the end-of-options delimiter, operands last) follows the utility conventions of the Open Group Base Specifications; many modern SDK CLIs add GNU-style long options such as --output=json. Shells add quoting, redirection and pipelines around this, which is why a documented command can be copied into a script unchanged.

A CLI is not a separate feature set. In most SDKs it is a client over the same application programming interface or build engine that the libraries use, which makes the command line a scriptable view of documented behavior rather than a second product.

How it applies

• Developer SDKs. Cloud CLIs (for example the AWS CLI) send the same requests as the language libraries do against a REST API, read profiles and credentials from a configuration file or environment variables, and can usually emit JSON for machine parsing. Document which authentication mechanism a command expects, and never claim that using the CLI by itself satisfies a security or regulatory requirement.
• Publishing SDKs. The DITA Open Toolkit is driven by the dita command, which takes an input DITA map, a transformation type and parameters; this makes DITA output generation reproducible in a pipeline and lets conditional processing profiles be selected per build instead of per author session.
• Platform SDKs. Extension toolkits expose CLIs for scaffolding a project skeleton, running schema validation on manifests, packaging and signing the artifact, and uploading it to a marketplace. The scaffolding step is usually a thin front end for automatic code generation.
• Hardware SDKs. Embedded toolchains wrap the compiler, linker, flasher and serial monitor in one front end — Espressif's idf.py is a documented example — so that building, writing firmware to a target and starting a debugging session are single commands. Document the required board, port and toolchain version, because a command that silently targets the wrong board produces misleading results.
• Documentation work. Reproduce commands verbatim in code blocks, name every required option, state the exit codes that automation should check, and pin the tool version you tested against, ideally with a semantic versioning range. Mark commands that change remote state or erase device memory.
• Engineering work. CLI flags, environment variables and configuration files form part of the tool's public surface; removing or renaming a flag is a breaking change for pipelines, so treat the CLI as an interface contract with its own deprecation notes.

CLI vs. API

An API is the programmatic contract a program calls in process or over a network; a CLI is a process a human or a script starts and whose output it parses. A CLI is therefore often narrower than the API behind it and shaped for automation ergonomics — exit codes, stable machine-readable output, idempotent commands. When both exist, the API is the authority for available operations, and the CLI documentation should say which API version or build engine it invokes.

External references

• The Open Group Base Specifications Issue 7 — Utility Conventions (rationale)
• The Open Group Base Specifications Issue 7 — Shell Command Language
• What is the AWS Command Line Interface?
• Android SDK Manager command-line tool
• DITA Open Toolkit documentation
• ESP-IDF: IDF Frontend (idf.py)