---
title: "CLI Design"
description: "Building CLIs that AI agents can operate as effectively as human users"
url: "https://agentsurface.dev/docs/cli-design"
lastVerified: 2026-09-24
lastModified: 2026-09-25T09:21:34.000Z
---



## Summary [#summary]

CLI Design covers command-line surfaces that agents can script without scraping terminal prose. Use it when a product exposes capabilities through commands, local automation, package scripts, or developer tools.

* **Owns:** command structure, JSON output, raw payload input, schema introspection, exit codes, context window discipline, input hardening, safety flags, and packaging CLI knowledge for agents.
* **Does not own:** model-callable tool schemas in general; see [Tool Design](/docs/tool-design). HTTP service contracts; see [API Surface](/docs/api-surface).
* **Agent-ready means:** every command can be discovered, invoked non-interactively, parsed structurally, retried safely, and diagnosed from exit status plus error body.

## Start Here [#start-here]

* [Command Structure](/docs/cli-design/command-structure) - Shape commands around stable resources and verbs.
* [Machine-Readable Output](/docs/cli-design/machine-readable-output) - Return parseable JSON, not terminal-only formatting.
* [Raw Payload Input](/docs/cli-design/raw-payload-input) - Accept files or stdin for complex structured input.
* [Schema Introspection](/docs/cli-design/schema-introspection) - Let agents discover commands and options programmatically.
* [Context Window Discipline](/docs/cli-design/context-window-discipline) - Keep help, logs, and results compact.
* [Input Hardening](/docs/cli-design/input-hardening) - Reject malformed arguments with actionable errors.
* [Safety Rails](/docs/cli-design/safety-rails) - Support dry runs, confirmations, and non-interactive execution.
* [Agent Knowledge Packaging](/docs/cli-design/agent-knowledge-packaging) - Ship command guidance agents can retrieve.
* [CLI Scale](/docs/cli-design/cli-scale) - Score a CLI against the seven-axis agent-readiness framework.

## Related [#related]

* [Error Handling: CLI Errors](/docs/error-handling/cli-errors) - Structured failures and stable exit codes.
* [Tool Design](/docs/tool-design) - Use when commands become model-callable tools.
* [Context Files](/docs/context-files) - Document canonical commands for coding agents.
* [Testing](/docs/testing) - Add contract tests for CLI output and failure modes.