aclif, the Agent CLI Framework, Is Open Source

The Service CLI described in our last two posts, on design-time authoring and run-time execution, is built on a framework we have now published as open source. aclif, the Agent CLI Framework, is available on GitHub at agent-cli-framework/aclif under the MIT license, and on npm as @aclif/core. Prompt One's own p1cli is a CLI built on it and is deployed in the Service Gateway as an embedded runtime.

aclif began as internal code. As our deployments multiplied, the set of external services an agent had to reach differed every time, from a single Salesforce org to several platforms with more than one instance of the same provider. Several of the customers behind those deployments had already connected agents of their own to the same platforms over MCP, and they asked whether the Service CLI's structured, deterministic access could serve those agents as well. We heard the request often enough to conclude that the approach is useful apart from our platform.

Making the code useful for teams building their own CLIs took more than just adding a license file. We refactored the runtime to support different deployment scenarios, and reorganized the repository and the build so that a private provider's code stays isolated from upstream. Every release is published to npm as @aclif/core, so a downstream CLI pins a version and takes updates on its own schedule.

If you are deploying agents in your organization and want them to be more reliable and more secure, consider giving them an aclif CLI. Every command declares what it will do before it runs, returns one JSON envelope with errors the agent can act on, and can run behind a gateway that holds the credentials in the agent's place.

See www.aclif.ai for more details.

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. A host can lower the cost with tool filtering or deferred loading, and a server can publish a generic call tool, but each of those is a design-time decision made per server, and it fixes which operations the agent can ever 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 AI 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.

What every command gives an agent

• One grammar. One command structure, one JSON envelope, and one error vocabulary across every provider. An agent learns the tool once.
• Canonical names. Alias sets map customer to Account in one Salesforce instance and core_company in ServiceNow, and --canonical resolves them.
• Errors an agent can act on. Every error names the failure, the command that fixes it, and where possible the corrected input ready to resend.
• Introspection without execution. --schema, --examples, --estimate, and the other introspection flags return before the command runs, need no credentials, and count against no API quota.
• An embeddable runtime. The same command classes run in-process inside a host that supplies credentials, identity, and policy per request.
• Declared safety. Mutability, blast radius, reversibility, idempotency, and whether confirmation is required are declared on every command, so a policy check can refuse it before its code loads.

The introspection-first workflow

An agent needs no documentation beyond the binary. It lists the providers, reads a briefing on the one it needs, reads a command's schema and examples, dry-runs the command, and only then executes it. Nothing before the last step touches the API. Every result is one JSON envelope holding the data returned, a pagination block with the complete command for the next page, and related commands. Exit codes distinguish API, usage, and authentication failures, so an agent can branch without parsing prose. The getting started page walks through the sequence, the envelope, and the error format.

For an agent that executes a defined workflow, it can perform discovery once at design time and embed the exact command string in the workflow. For an agent that reasons at run time, the package includes a skill that tells it to introspect before it runs a command.

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, with credentials in its own config file and output meant for a terminal.

Behind a gateway, that design 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 before it runs, and every tool reports in its own format, so there is nothing uniform to audit.

aclif overcomes these limitations by separating the command from the process that runs it. The same command classes run unchanged in three ways, and whoever runs them supplies the credentials, enforces policy, and keeps the audit trail.

1. Run by the agent. The agent spawns the binary and reads the JSON it returns, the way a coding agent runs git or gh.
2. Run by a host application. An application sits between the model and aclif, holds the credentials, and executes each command in-process. The model never sees a credential.
3. Run by a gateway. One long-lived process serves many deployed agents, resolves credentials from the enterprise vault, checks policy against the acting user, and records every call.

Prompt One runs the second and third cases. Composer, the authoring tool, deploys as a host application and uses the embedded runtime to discover, introspect, and validate every command it writes into a Motion. The Service Gateway runs as a gateway, resolving credentials from a vault and applying its capability check on every call.

Providers

Every provider sits in one of three tiers, and the tier indicates who maintains it and whether it is included in the release. Five providers come with the binary. Salesforce, ServiceNow, DocuSign, and Agentforce are in the native tier and are maintained by the project, with live smoke tests against real instances. Google Workspace is in the contributed tier, maintained by the people who wrote it, and packaged with the release. A provider in the private tier is one a team writes for its own CLI and does not send upstream. It lives in a directory the upstream project never commits to, so the team can pull new aclif releases without conflicts. All three tiers run through the same conformance suite.

A coding agent can write a provider from the platform's API specification, and PROVIDER_AUTHORING.md includes a sample generation prompt.

Build your own CLI

aclif is built on oclif, the CLI framework used by Salesforce, Adobe, and many others. @oclif/core is taken as an ordinary dependency, and a scaffold command produces a CLI with its own name, config directory, and environment variables, and only the providers it chose. This is how p1cli is built: the native providers it needs plus three private ones. Build a CLI covers the scaffold and the fork path.

Contributing

More native providers are planned, and contributed providers are welcome. Contributions follow CONTRIBUTING.md, security reports follow SECURITY.md, and the FAQ covers the questions we have been asked most often.

The whitepaper Enterprise Agents, Compiled sets out the architecture aclif was built to serve, and if your team has a motion it wants compiled, start a free trial and watch the Service CLI run on your own systems.

1. Prompt One's Composer is the authoring tool on our platform. It runs aclif's embedded runtime to discover providers, read each command's schema and examples, and validate the exact command it writes into the Motion, as described in the design-time post.