The Agent CLI Framework

aclif builds command-line tools for AI agents. An agent gets a single tool that provides a unified abstraction across every SaaS provider: one grammar, and canonical names that reach the same record by the same name on any platform.

Try it now

Install the binary, list the providers, and read a command's schema, examples, and safety metadata.

npm install -g @aclif/core

aclif discover --json
aclif learn salesforce --json
aclif learn servicenow --json
aclif salesforce data query --schema
aclif salesforce data query --examples
aclif salesforce data query --query "SELECT Id FROM Account LIMIT 3" --dry-run
aclif servicenow data query --table incident --query "active=true^priority=1" --dry-run

Getting started GitHub

Why agents need their own CLI

An MCP server publishes a fixed list of tools, and every tool on the list occupies the agent's context on every turn. The server's author trades coverage for cost when the server is built. Publishing every operation (a typical API has hundreds of definitions) keeps the whole API reachable and consumes tokens for all of it on every turn. Publishing a handful of broad operations keeps the token count small, and any operation the author left off the list is out of the agent's reach. An agent that spans several platforms needs a server, a login, a grammar, an error format, and a set of names for each.

aclif loads a command's definition only when the agent asks for it, so the whole API of every provider is reachable at no standing cost in context. One grammar, one envelope, and one error vocabulary cover every provider, so the agent's context stays about the same size whether it reaches one platform or five.

An agent that runs a defined workflow can leave the model out of the call altogether. A person or an authoring tool works out the exact command at design time and embeds it in the workflow as a string. At run time the agent executes that string as ordinary code, with no tool definition loaded and no inference. The command is chosen at design time, and the authority to run it, the credential, the acting identity, and the policy, is supplied at run time by whatever runs it. Neither side ever holds both.

What every command gives you

One grammar

One command structure, one JSON envelope, and one error vocabulary across every provider. An agent learns the tool once, and a new platform adds commands without adding grammar. A JSON manifest adds a command over one HTTP endpoint in the same grammar, with no code.

Canonical names

Alias sets map customer to Account in one Salesforce instance and core_company in ServiceNow. A tenant catalog, captured from each instance at deploy time, teaches the CLI each instance's custom objects and fields with no change to the provider.

Errors an agent can act on

An agent recovers in one turn. Every error names the failure, the command that fixes it, and, where the provider's classifier has a rewrite rule for the mistake, the corrected input ready to resend. The classifier is plain code with no model behind it. A command validated in a shell at design time returns the same error at run time under any host, because the same command classes run in both.

Introspection without execution

--schema, --examples, --shape, and four more flags return before the command runs, need no credentials, and count against no API quota. An agent can discover, learn, introspect, and preview against a rate-limited instance and spend nothing.

An embeddable runtime

The same command classes run in-process inside a host that supplies credentials, identity, and policy per request, keeps connections warm, and caches expensive logins per instance. A gateway built on it works with the enterprise's own identity provider and secrets vault.

Declared safety

Mutability, blast radius, reversibility, and idempotency are declared on every command. A policy check can refuse it before its code loads. Every mutation accepts --dry-run, demands --confirm where its metadata says so, and writes an audit line after every run.

The introspection-first workflow

An agent needs no documentation beyond the binary, and nothing before the last step touches the API.

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

The envelope's _context block holds pagination with the exact next command, the fields available, and related commands worth running. Exit codes are 0, 1 (API), 2 (usage), 3 (authentication). The contract and its JSON Schemas are in CONTRACT.md.

Three ways to run it

A vendor CLI is built for one deployment: installed on a machine, logged in by the person at the keyboard, one process per command. Behind a gateway that fails. Every call spawns a process and logs in again, the acting user's identity cannot be forwarded, nothing declares what a command will do, and nothing is uniform to audit. aclif's command classes run unchanged in three places, and whoever runs them decides who supplies credentials, enforces policy, and keeps the audit trail.

Run by the agent. The agent process spawns the binary, executes the command, and reads the JSON it returns. Credentials come from flags, environment variables, or a profile in the agent's own environment. Use this when one agent, one operator, and one set of credentials share a trust boundary.
Run by a host application, the design-time case. An application sits between the model and aclif and holds the credentials. The model calls a tool the application defines, and the application executes the command, in-process or by passing a command string to the CLI. A person or an authoring tool uses this to let a model discover providers, introspect commands, and validate the exact command it will write into an agent. Use this when the model must never hold credentials and tool definitions must stay out of its context.
Run by a gateway, the runtime case. A deployed agent submits commands, and one long-lived process serves many such agents. The gateway resolves credentials from the enterprise vault per request, checks policy against the acting user, records every call, and keeps connections warm. The agents hold no provider credentials and cannot widen their own scope. Use this when many agents share providers and one place must hold policy and audit.

	Run by the agent	Run by a host application	Run by a 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	the acting user on the invocation	the acting 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 instance and identity

Details on the Embedding page.

Gateway deployments

Long-lived, embeddable deployment enables a gateway topology where additional security policy can be applied. One process the enterprise operates executes every command for every agent, and the arrangement provides:

Credentials in one place. Resolved inside the gateway, per request, from the enterprise's vault. Agents hold none.
Enterprise-wide canonical names. Tenant catalogs and alias sets are held by the gateway, so every agent uses the same names for the same records across every provider and instance.
Every call attributed to a person. The acting user's identity travels with each call into the policy check and the audit record, even through a shared service account.
Policy enforced once. Every command declares what it will do, and the gateway checks that declaration before the command's code loads. Agents cannot widen their own scope.
One audit trail. The same event for every command from every agent, naming the user, the command, and the outcome.

Install, or build your own

npm install -g @aclif/core

# Your org's My Domain URL, no trailing slash
export SF_INSTANCE_URL=https://example.my.salesforce.com

# A session token from the Salesforce CLI (sf org login web first if needed)
export SF_ACCESS_TOKEN=$(sf org auth show-access-token -o me@example.com --json | jq -r .result.accessToken)

aclif salesforce data query --query "SELECT Id, Name FROM Account LIMIT 3" --json

Without the Salesforce CLI, use an API user. Salesforce emails the security token when the password is set or reset:

export SF_INSTANCE_URL=https://example.my.salesforce.com SF_USERNAME=me@example.com SF_PASSWORD=... SF_SECURITY_TOKEN=...
aclif salesforce data query --query "SELECT Id, Name FROM Account LIMIT 3" --json

The aclif binary ships with every built-in provider and needs Node 22 or later. The binary you ship is yours: one scaffold command produces a CLI with its own name, its own config directory, its own environment variables, and only the providers it chose. See Getting started and Build a CLI.

Providers

Salesforce, ServiceNow, DocuSign, and Agentforce are native and are included in every release. Google Workspace (Gmail, Calendar) is contributed. A private tier holds providers a fork keeps to itself, under a path upstream never commits to. Writing a provider takes little effort: it is a direct translation of the platform's API specification onto the command surface, a coding agent does it from a sample prompt in the repository, and the conformance suite checks the result. See Providers.

aclif is MIT licensed. Contributions follow CONTRIBUTING.md; the guide for people and coding agents changing the framework is AGENTS.md.