Building CLIs for AI Agents: Design Principles from Google's gws CLI

Why Agent-First CLI Design Matters

Human developer experience (DX) optimizes for discoverability and forgiveness, while agent DX requires predictability and defense-in-depth. The article argues that retrofitting human-first CLIs for agents is ineffective, and demonstrates this through Google's gws CLI for Google Workspace, which was designed from day one with AI agents as the primary consumers.

Key Design Principles

Raw JSON Payloads Over Bespoke Flags: Humans prefer simple flags like --title "My Doc", but agents work better with direct JSON payloads that map to API schemas without translation loss.

Example comparison:

Human-first (10 flags, flat namespace):
my-cli spreadsheet create --title "Q1 Budget" --locale "en_US" --timezone "America/Denver" --sheet-title "January" --sheet-type GRID --frozen-rows 1 --frozen-cols 2 --row-count 100 --col-count 10 --hidden false

Agent-first (one JSON flag):
gws sheets spreadsheets create --json '
{
  "properties": {"title": "Q1 Budget", "locale": "en_US", "timeZone": "America/Denver"},
  "sheets": [{"properties": {"title": "January", "sheetType": "GRID", "gridProperties": {"frozenRowCount": 1, "frozenColumnCount": 2, "rowCount": 100, "columnCount": 10}, "hidden": false}}]
}'

The gws CLI uses --params and --json flags for all inputs, accepting full API payloads directly. The recommended approach is to support both paths in the same binary rather than maintaining separate tools.

Additional Considerations

The article outlines several other design considerations for agent-first CLIs:

• Schema Introspection: Self-describing schemas that agents can introspect at runtime
• Context Window Discipline: Managing output to fit within agent context limits
• Input Hardening: Protection against agent hallucinations
• Agent Skills: Shipping capabilities rather than just commands
• Multi-Surface Support: Working with MCP, extensions, and environment variables
• Safety Rails: Dry-run modes and response sanitization

CLIs are becoming the lowest-friction interface for AI agents to interact with external systems, requiring deterministic, machine-readable output rather than human-oriented interfaces.