CLI Execution & Natural Language
Relevant source files
The following files were used as context for generating this wiki page:
The CLI Execution & Natural Language system defines the standards and implementation patterns for Command Line Interfaces (CLIs) designed to be consumed by both humans and AI agents. This system bridges the gap between structured machine execution and natural language intent by enforcing a "Default-to-JSON" output philosophy while maintaining human-readable interfaces via specific flags. It ensures that CLI tools are verifiable, stable, and self-describing, allowing agents to discover capabilities, execute complex tasks, and handle errors autonomously.
In this project, the system is represented through several specialized skills that automate project scaffolding, audit codebases before execution, and manage the lifecycle of AI-specific documentation like AGENTS.md and SKILL.md. These components work together to create a robust execution environment where natural language prompts are translated into reliable terminal commands.
Sources: bundled-skills/ai-native-cli/SKILL.md, bundled-skills/agents-md/SKILL.md
1. AI-Native CLI Architecture
The architecture of the CLI execution layer is built on a "Layer Model" that categorizes tool compliance into three levels: Agent-Friendly, Agent-Ready, and Agent-Native. This model ensures that as a tool evolves, it remains compatible with automated agents that rely on structured output and predictable exit codes.
1.1 The Layer Model
The system uses layers to define the rollout scope and certification of a CLI tool.
| Level | Goal | Primary Requirement |
|---|---|---|
| Agent-Friendly | Stable calling API | JSON by default, predictable exit codes. |
| Agent-Ready | Self-describing | Structured help, no positional ambiguity. |
| Agent-Native | Closed-loop collab | Inline context, skills system, feedback loop. |
Sources: bundled-skills/ai-native-cli/SKILL.md:43-57
1.2 Execution Data Flow
The data flow within the CLI execution system prioritizes structured data (JSON) for agents while reserving the Standard Error (stderr) for logs, progress, and warnings.
The diagram shows how natural language prompts are parsed into commands, processed by the CLI logic, and returned as structured data for agent interpretation.
Sources: bundled-skills/ai-native-cli/SKILL.md:99-105, bundled-skills/ai-native-cli/SKILL.md:120-123
2. Structured Output and Error Handling
For natural language agents to execute CLI commands reliably, the system enforces strict output contracts. This eliminates the need for complex regex parsing of human-readable text.
2.1 Default JSON Output
A core rule of the system is that default output must be JSON. Human-friendly formatting (colors, tables) is only activated via an explicit --human flag.
- Rule O1: Default output is JSON. No
--jsonflag needed. - Rule C1: stdout is for data ONLY.
- Rule C2: Logs, progress, and warnings go to stderr ONLY.
Sources: bundled-skills/ai-native-cli/SKILL.md:99-105, bundled-skills/ai-native-cli/SKILL.md:120-123
2.2 Standardized Exit Codes
Predictable exit codes are used to signal the nature of failure without requiring the agent to parse error messages for logic.
| Exit Code | Meaning | Usage |
|---|---|---|
| 0 | Success | Operation completed successfully. |
| 1 | General Error | Catch-all for non-specific failures. |
| 2 | Param Error | Missing required arguments or invalid type mismatch. |
| 10 | Auth Error | Authentication expired or failed. |
| 20 | Not Found | Resource or file not found. |
Sources: bundled-skills/ai-native-cli/SKILL.md:109-117, bundled-skills/ai-native-cli/SKILL.md:195-201
3. Automation and Scaffolding Patterns
The project utilizes specific patterns for generating CLI projects and managing project context to ensure consistency across different languages (primarily Rust and Python).
3.1 Rust Project Scaffolding
The systems-programming-rust-project skill automates the creation of binary projects with structured CLI parsing using the clap crate. This enforces a standardized directory structure and command-line argument definition.
This structure ensures that CLI logic is separated from business logic, facilitating easier agent navigation and maintenance.
Sources: bundled-skills/systems-programming-rust-project/SKILL.md:46-63
3.2 Context-Preserving Logs (Diary System)
The diary skill manages a multi-step atomic workflow that captures project state and converts it into a global context for AI agents. This process identifies the project root, archives progress, and syncs to external knowledge bases.
Atomic Workflow Steps:
- Identify: Detect project name via
pwd. - Write: Local project archiving (achievements, changes).
- Context Refresh: Update
AGENT_CONTEXT.mdusingprepare_context.py. - Global Fusion: Sync across projects while maintaining a "Context Firewall" to prevent data pollution.
Sources: bundled-skills/diary/SKILL.md:15-62
4. Agent Documentation and Discovery
To support autonomous execution, the system relies on specialized documentation files that describe the project's identity and constraints.
4.1 AGENTS.md / CLAUDE.md
This file serves as the canonical agent-facing documentation. It is designed to be minimal (under 60-100 lines) to prevent quality degradation in agent instruction following. It focuses on:
- Package Manager: Canonical commands (e.g.,
pnpm install). - File-Scoped Commands: Targeted tasks for typechecking, linting, and testing.
- Commit Attribution: Standards for AI-authored commits.
Sources: bundled-skills/agents-md/SKILL.md:10-50
4.2 The agent/ Directory Convention
For CLI tools, an agent/ directory must exist at the project root to house behavior contracts.
agent/
brief.md # One paragraph identity
rules/ # Behavior constraints
trigger.md # When to use the tool
workflow.md # Usage flow
skills/ # Extended capabilities
Sources: bundled-skills/ai-native-cli/SKILL.md:80-92
5. Security and Guardrails
The CLI execution system includes "Zero Tolerance" security guardrails to prevent agents from performing dangerous actions or leaking sensitive data.
5.1 Destructive Operations
All destructive operations (e.g., delete, destroy) require a --yes flag. Agents are instructed never to enter interactive mode; if a confirmation is missing, the tool must exit non-zero immediately.
Sources: bundled-skills/ai-native-cli/SKILL.md:131-133
5.2 Input Validation Guardrails
The system implements runtime protection against common injection and leakage risks:
- Rule G2: Detect and reject API keys or tokens in command arguments.
- Rule G3: Reject sensitive file paths (e.g.,
*.env,*.key,*.pem). - Rule G8: Reject shell metacharacters (
|,;,&&,$()) in arguments to prevent command injection.
Sources: bundled-skills/ai-native-cli/SKILL.md:143-149
5.3 Audit Checks
The codebase-audit-pre-push skill performs a deep review of files before they are pushed to GitHub, specifically targeting:
- Secret Detection: Checking for hardcoded passwords and tokens.
- Junk Removal: Deleting
.DS_Store, logs, and temporary build outputs. - Dead Code: Identifying unused imports and variables that increase cognitive load for agents.
Sources: bundled-skills/codebase-audit-pre-push/SKILL.md:32-65
Summary
The CLI Execution & Natural Language system is a rigorous framework for building and managing interfaces that are optimized for AI agent interactions. By mandating structured JSON output, predictable error codes, and explicit security guardrails, the system ensures that complex software tasks can be executed reliably through natural language. Documentation files like AGENTS.md and the agent/ directory serve as the "identity" for tools, providing the necessary context for agents to discover and safely employ the repository's capabilities.