xiry.

Development · Article or course

You Need to Rewrite Your CLI for AI Agents

Architectural guide for designing command-line tools tailored for AI agent execution

From the Xiry library · Updated 10 October 2026

Visit justin.poehnelt.com ↗

Justin Poehnelt outlines the architectural principles behind designing CLIs specifically for AI agents, drawing from work on the Google Workspace CLI. It highlights that human DX prioritizes discoverability while agent DX requires predictability, context-window discipline, and strict input hardening. The article provides concrete steps for adapting tools with JSON payloads, schema introspection, and MCP integration.

What it's for

  • Design or refactor a CLI tool for AI agents and LLM orchestration
  • Harden command-line arguments and file outputs against model hallucinations
  • Expose CLI interfaces as Model Context Protocol (MCP) tools
  • Reduce context window overhead in automated agent API workflows

Features

  • Accept raw JSON payloads instead of relying on bespoke flags
  • Support runtime schema introspection to eliminate static system-prompt documentation
  • Implement context-window controls like field masks and NDJSON pagination
  • Harden input paths, control characters, and IDs against adversarial hallucinations
  • Distribute structured skill files (SKILL.md) to define operational invariants
  • Support multi-surface invocation including standard CLI, MCP stdio, and env-var auth
  • Incorporate pre-execution dry-runs and response sanitization against prompt injection

Pricing

Free

Details

Type
Article or course
Category
Development
Topic
CLI Design
Open source
No
Platforms
Web
For
Software engineers and tool builders creating CLIs or MCP servers for AI agents
Tags
cli, ai agents, mcp, developer experience, architecture, security

Why it was saved

  • @rauchg, 5 March 2026: Explains the design philosophy behind agent-first CLIs: human DX optimizes for discoverability, agent DX optimizes for predictability.

Related

  • Google Workspace CLI

    Command-line tool and agent skills for managing Google Workspace services

  • Firecrawl

    Turn websites and documents into clean, LLM-ready markdown or structured data.

  • agent-browser

    Browser automation CLI and engine purpose-built for AI agents

  • Parse

    Turn any website into a structured REST API using natural language

  • pen.dev

    Agentic canvas and IDE extension for building UI designs directly into code

  • Agent-Ready SaaS Checklist

    Practical rules for preparing SaaS APIs and infrastructure for AI agents

Updated