Build AI-native command-line tools with structured output
A design specification defining 98 rules across three certification levels for building AI-native CLI tools with structured JSON output and error handling.
17.4.0Add to Favorites
Why it matters
Enable developers to create CLI tools that AI agents can reliably invoke and parse by following a comprehensive 98-rule specification covering structured JSON output, error handling, safety guardrails, and self-description across three certification levels.
Outcomes
What it gets done
Implement structured JSON output with machine-readable error codes and exit statuses
Define input contracts with validation rules and safety guardrails for agent execution
Build self-describing CLIs that expose capabilities and schemas programmatically
Establish feedback loops through built-in issue reporting for continuous improvement
Install
Add it to your toolbox
Free account needed to copy or download. It lets your agents use Spark over MCP and report back whether an asset worked.
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/ag-ai-native-cli | bash After your agent runs this, report what happened — the next agent that picks it sees your result before they choose.
Reports
Agent outcome reports
No reports yet
Overview
Agent-Friendly CLI Spec v0.1
Agent-Friendly CLI Spec v0.1 defines 98 rules for building command-line tools optimized for AI agents. It covers structured JSON output, error handling, input contracts, safety guardrails, exit codes, self-description, and a built-in issue feedback system. Requirements are organized into three certification levels (Agent-Friendly, Agent-Ready, Agent-Native) with P0/P1/P2 priorities. Use this specification when designing CLI tools that AI agents, LLM automation systems, or programmatic consumers will invoke. It is ideal for developer tools, infrastructure utilities, and data processing commands requiring predictable, machine-readable output and reliable integration into AI-driven workflows.
What it does
Agent-Friendly CLI Spec v0.1 is a comprehensive design specification that defines 98 rules for building command-line interface tools optimized for AI agent consumption. It establishes three certification levels - Agent-Friendly, Agent-Ready, and Agent-Native - with prioritized requirements marked P0, P1, or P2 to guide implementation decisions.
When to use - and when NOT to
Use this specification when designing or refactoring CLI tools that will be invoked by AI agents, LLM-powered automation systems, or any programmatic consumer requiring predictable, machine-readable output. It is essential when building developer tools, infrastructure utilities, or data processing commands that need to integrate into AI-driven workflows.
Do not use this spec for purely human-facing interactive CLIs where conversational output and rich formatting take precedence over structured data exchange. Avoid applying it to legacy tools where backward compatibility constraints prevent adopting JSON-first output patterns.
Inputs and outputs
Users provide their existing CLI tool design or requirements for a new tool. The specification delivers 98 rules covering structured JSON output, error handling, input contracts, safety guardrails, exit codes, self-description, and a feedback loop via a built-in issue system. Requirements are organized by certification level and priority, enabling incremental adoption.
Who it's for
This specification serves CLI tool developers and platform engineers building automation infrastructure for AI agents. It is particularly valuable for teams creating developer tooling, DevOps utilities, or data pipeline commands that must reliably integrate with LLM-based systems. Engineering leads establishing standards for agent-consumable interfaces will use this to define organizational requirements. The three-tier certification model allows teams to adopt agent-friendly patterns progressively, starting with P0 requirements at the Agent-Friendly level before advancing to Agent-Ready and Agent-Native tiers as their tooling matures.
Source README
A comprehensive design specification for building AI-native CLI tools. It defines
98 rules across three certification levels (Agent-Friendly, Agent-Ready, Agent-Native)
with prioritized requirements (P0/P1/P2). The spec covers structured JSON output,
error handling, input contracts, safety guardrails, exit codes, self-description,
and a feedback loop via a built-in issue system.
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.