Agentics: Design Principles for Building an Agent-First CLI

Summary

theahura argues that for critical agent integrations, purpose-built CLIs beat MCP servers — which "consume excessive tokens and often have poor implementations" — because CLIs give progressive disclosure for free, match how models already reach for bash, and ride heavy CLI training data. The post distills a concrete rule set for making command-line tools agent-first.

Key Details

• No visual flourishes — drop color, spinners, animations; they burn tokens with zero agent value.
• Complete non-interactivity — every function reachable via flags + stdout/stderr (no prompts).
• Comprehensive help — empty call, --help, and --list return full capability/command docs.
• Recursive documentation — each command level documents its own parameters (100% coverage).
• Error guidance — errors carry file paths and nudge the agent to read source.
• Source availability — install-from-source or bundled code so agents can self-troubleshoot.
• Self-correction — "Did you mean…" suggestions on invalid commands.
• Reference implementations: the open-source nori-*-cli tools (Slack, SES newsletters, Luma, Discord, Shopify).

Why This Matters

Further Reading

• Agentics: Design Principles for Building an Agent-First CLI