A command-line framework for AI agents

aclif builds CLIs that agents can learn on demand, that declare what each command will do before it runs, and that run the same way from a shell, inside a tool call, or behind a gateway serving many agents at once.

oclif is the framework behind the Salesforce, Shopify, Adobe, and Twilio CLIs. It solved the hard parts of building a command-line tool for people: parsing flags, routing commands, generating help, loading plugins. aclif uses it as an ordinary, unforked dependency and adds what a tool needs when the one typing is an AI agent.

Why a CLI

Two published arguments decided the design. Justin Poehnelt's The MCP Abstraction Tax observes that every layer between an agent and an API loses fidelity, and that a tool server must either reduce the API to a few operations or load every definition into context on every turn. A command-line tool whose documentation loads on demand avoids both costs. Prompt One's Your Agent Should Never Choose Its Own Tools argues that a workflow agent's commands should be chosen, validated, and fixed at design time under a person's identity, and that an agent holding live credentials while reading untrusted content is where prompt injection does its damage. Both arguments, restated with their sources, are in the repository's MOTIVATION.md.

What an agent gets

One grammar

One command structure, one JSON envelope, and one error vocabulary across every provider. An agent learns the tool once.

Introspection without execution

--schema, --examples, --shape, and five more flags answer without credentials and without running anything.

Declared safety

Every command states whether it reads, writes, or deletes, how many records it touches, and whether it can be undone. A policy gate can refuse it before its code loads.

Actionable errors

Every error carries a code, a hint naming the command that fixes it, and where possible a corrected value ready to resend.

Canonical names

Alias sets map your names for entities and fields onto each platform's native names, so customer resolves to Account in one org and Company in another.

An embeddable runtime

The same command classes run in-process inside a host that supplies credentials, identity, and policy per request and keeps connections warm.

The introspection-first workflow

An agent needs no documentation beyond the binary.

aclif discover --json                          # every provider, its tier, whether credentials are configured
aclif learn salesforce --json                  # a briefing: topics, key fields, query syntax, auth paths
aclif salesforce data query --schema           # flags, args, safety metadata, no execution
aclif salesforce data query --examples         # runnable examples with the responses they produce
aclif salesforce data query --query "SELECT Id, Name FROM Account LIMIT 5" --dry-run
aclif salesforce data query --query "SELECT Id, Name FROM Account LIMIT 5" --json

Every result is one envelope. The _context block carries pagination with the exact next command, the fields available, and related commands worth running.

{
  "success": true,
  "result": {"records": [{"Id": "001xx", "Name": "Acme"}], "totalSize": 1, "done": true},
  "_context": {
    "contract": "1.0.0",
    "pagination": {"returned": 1, "total": 1, "hasMore": false, "nextCommand": null},
    "relatedCommands": ["aclif salesforce discover --object Account --verbose"]
  }
}

Where it runs

A vendor CLI is built for one deployment: installed on a machine, logged in by the person at the keyboard, one process per command. aclif is one package whose command classes run unchanged in three deployments. The host decides who supplies the credentials, who enforces policy, and who keeps the audit trail.

	Binary on PATH	Tool call, in-process	Gateway
Credentials	flags, env, `config.yaml`	host-supplied resolver	vault-backed resolver, per request
Policy	`config.yaml`	`capabilityGate` hook	`capabilityGate` plus the host's middleware
Identity	`--identity-token` or env	`context.user`	`context.user` and SSO claims from the request
Audit	stderr line per run	reporter events	reporter events, recorded by the host
Connections	file session cache	runtime pool	runtime pool, keyed per tenant and identity

Details for each deployment are on the Embedding page.

Start

Getting started: install the reference binary and run the introspection workflow.
Build a CLI: scaffold your own binary with your own name and providers.
Providers: what ships, the three tiers, and how a new provider is written.
The contract: the envelope, errors, exit codes, metadata, and the JSON Schemas behind them.