ACLI — Agent-friendly CLI¶

Build CLI tools that AI agents can discover, learn, and use autonomously.

ACLI is a lightweight specification for designing CLI tools that agents can bootstrap at runtime — without pre-loaded schemas or external tool registries. The core insight: a well-designed CLI is self-documenting enough that an agent can learn it on demand by running <tool> --help.

How it works¶

Agent tool integration has evolved through three stages:

MCP           → schema defined externally, injected at agent startup
SKILLS.md     → instructions written by humans, loaded into context
<cli> --help  → tool teaches itself to the agent on demand

ACLI targets the third stage — where the tool is the source of truth, not an external schema or a hand-written doc. Read the full comparison in Why ACLI? MCP → Skills → CLI.

Key principles¶

Progressive Discovery — learn the full capability surface incrementally, starting from --help
Machine-readable by default — structured output (JSON) is a first-class citizen
Fail informatively — errors teach, not just reject
Safe exploration — reason about actions before committing via --dry-run
Consistent contracts — exit codes, output formats, and error shapes are predictable

Quick start¶

Install the Python SDK¶

pip install acli-spec

Build your first ACLI tool¶

from pathlib import Path
from acli import ACLIApp, acli_command, OutputFormat
import typer

app = ACLIApp(name="myapp", version="1.0.0")

@app.command()
@acli_command(
    examples=[
        ("Run a task", "myapp run --file task.yaml"),
        ("Dry-run a task", "myapp run --file task.yaml --dry-run"),
    ],
    idempotent=False,
)
def run(
    file: Path = typer.Option(..., help="Path to task file. type:path"),
    dry_run: bool = typer.Option(False, help="Preview without executing."),
    output: OutputFormat = typer.Option(OutputFormat.text),
) -> None:
    """Execute a task from a YAML file."""
    ...

if __name__ == "__main__":
    app.run()

You automatically get:

myapp introspect — full command tree as JSON
myapp version — semver output with --output json support
.cli/ folder with README, examples, and schemas
JSON error envelopes with actionable hints
Semantic exit codes (0–9)

SDKs¶

Language	Status	Install / location
Python	Published	`pip install acli-spec`
Rust	Published	`cargo add acli`
TypeScript	Published	`npm install @acli/sdk`
Go	In monorepo	`sdks/go`
.NET	In monorepo	`sdks/dotnet`
R	In monorepo	`sdks/r`
Java	In monorepo	`sdks/java`

See SDKs overview for details, README links, and examples.

License¶

EUPL-1.2