aclif, the Agent CLI Framework

Overview
Getting started
Build a CLI
Embedding
Providers
FAQ
v1.3.0

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 agentRun by a
host applicationRun by a gateway

Credentialsflags, env,
config.yamlhost-supplied resolvervault-backed
resolver, per request
Policyconfig.yamlcapabilityGate
hookcapabilityGate plus the host's
middleware
Identity--identity-token or
envthe acting user on the invocationthe
acting user and SSO claims from the request
Auditstderr line per runreporter
eventsreporter events, recorded by the host
Connectionsfile session cacheruntime
poolruntime 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.

aclif is MIT licensed. Copyright (c) 2026 Prompt
One, Inc.

The Agent CLI Framework, or aclif, is designed to build command-line tools specifically for AI agents by providing a unified abstraction layer across various Software as a Service (SaaS) providers. Its core philosophy addresses the inefficiencies of current agent architectures where agents must manage numerous, disparate tools. aclif achieves this unification by ensuring that an agent interacts with all platforms through a single grammar, a standardized JSON envelope, and consistent naming conventions, allowing agents to maintain context size regardless of the number of supported platforms.

The framework tackles the challenge of context management by deferring the loading of command definitions until the agent explicitly requests them. This approach avoids the high token consumption associated with publishing the entire API of every provider, a limitation where publishing every operation leads to excessive token usage on every turn. Instead, aclif allows the agent to access the full API of every provider at no standing cost in context by ensuring one grammar, one envelope, and one error vocabulary cover all platforms. Furthermore, canonical names are established through alias sets that map customer entities, such as an Account in Salesforce, to a core_company in ServiceNow, which are captured from each instance at deployment time, thus teaching the CLI about provider-specific objects without modifying the provider's own structure.

aclif provides sophisticated mechanisms for agent interaction and safety. It allows agents to recover from errors in a single turn by defining error handling where every failure specifies the error, the necessary corrective command, and potential rewrite rules if the provider offers them. This error classification mechanism is implemented via plain code rather than relying on a model. Introspection is also supported through flags like --schema and --examples, which allow agents to discover, learn, introspect, and preview commands without requiring credentials or consuming API quota, enabling agents to interact with rate-limited instances without execution.

The framework supports an embeddable runtime where command classes execute in-process within a host application, allowing credentials, identity, and policy to be supplied per request, which keeps connections warm and caches expensive logins. This embedding capability facilitates a gateway topology where a single, long-lived process manages multiple agents, providing centralized control over security policy, audit logging, and credential resolution. This gateway ensures that agents operate using enterprise-wide canonical names and that every invocation is attributed to an acting user, thereby keeping the agent's scope tightly controlled and ensuring a comprehensive audit trail.

aclif defines three distinct modes for execution: running via a vendor CLI, running by the agent, and running via a gateway. The vendor CLI mode results in fragmented processes where identity cannot be forwarded and auditing is inconsistent. In contrast, running by the agent involves the agent spawning the binary itself and using credentials from its own environment, suitable when a single agent and operator share a trust boundary. Running by a host application is designed for the design-time workflow, where an external application manages credentials and dictates the command structure, allowing models to validate commands before interaction. Finally, the gateway mode serves as the runtime execution path, centrally resolving credentials from an enterprise vault, enforcing policy checks against the acting user, and recording detailed audit events for every command executed.

The framework natively supports providers such as Salesforce, ServiceNow, DocuSign, and Agentforce, with Google Workspace functionality contributed. The implementation is MIT licensed, and contributions to the framework are guided by the specified documentation for agents and contributors .