Build your own CLI

Define your own CLI supporting providers that you choose.

Scaffold

npx --package @aclif/core aclif-scaffold-cli --name mycli --dir ../mycli --providers salesforce,servicenow
cd ../mycli && npm install && npm run build
./bin/run.js discover --json

Here mycli becomes the name for your CLI. The scaffold writes a package.json file that includes the oclif configuration, a bin/run.js, a topic generator, a dependency allowlist for your own providers, a vitest config, and a conformance test. npm test runs that test. The scaffold installs @aclif/core under the alias aclif, so your code imports from aclif.

// src/index.ts
import {defineCli, type DefinedCli} from 'aclif'
import {salesforcePlugin, servicenowPlugin} from 'aclif/providers'

const cli: DefinedCli = defineCli({
  bin: 'mycli',
  providers: [salesforcePlugin, servicenowPlugin],
})
export const COMMANDS: DefinedCli['COMMANDS'] = cli.COMMANDS
export const registry: DefinedCli['registry'] = cli.registry

What the name changes

Surface	`mycli` gets
Command strings in examples, hints, and next-command suggestions	`mycli salesforce data query ...`, rendered at emit time from the configured binary name
Config and cache directories	`~/.config/mycli/config.yaml`, `~/.cache/mycli/`
Framework environment variables	`MYCLI_PROFILE`, `MYCLI_INSTANCE`, `MYCLI_IDENTITY_TOKEN`, `MYCLI_IDENTITY_SECRET`, `MYCLI_NO_MANIFESTS`, `MYCLI_CONFIG_DIR`
Audit line, `auth status`, `discover`, `learn`	this CLI's providers only

Everything else is the framework's: the envelope, the error vocabulary, the introspection flags, credential resolution, the connection pool, the session cache, and the embedded runtime.

Provider instances

A provider describes a platform. An instance is one deployment of that platform, such as a single Salesforce org, with its own credentials and its own custom objects, custom fields, and picklist values. Your CLI learns those customizations after it is built. mycli <provider> introspect --bootstrap walks the instance once and captures them into a tenant catalog, and from then on learn and --schema use that instance's own names. A custom object added next month is picked up by --refresh. No provider code changes and no rebuild.

Add your own provider

Writing one takes little effort when a coding agent does the work. Most of a provider is a direct translation of the platform's API specification: each operation becomes a command, its parameters become flags, its enumerations become flag options, and its method and path decide the safety metadata. PROVIDER_AUTHORING.md includes a sample generation prompt. Fill in the provider's name, tier, spec file, and auth scheme, and the coding agent generates the provider, runs the conformance suite, and fixes what fails.

Test your providers

The framework's conformance suite is importable from aclif/testing, and the scaffold writes a test that runs it over the providers your package declares.

npm run build && npm test

Upgrade the framework

npm update aclif. Your providers and your name are in your tree. The framework's changes arrive as a dependency bump. Nothing in the framework repository needs to know your CLI exists.

When to fork instead

Build a CLI package as described here unless you also need to change the framework's core. A team that does change core forks the repository and keeps its providers under src/providers/private/, a prefix upstream does not commit, so pulling upstream stays conflict-free and core fixes go back from a clean branch.

The full guide is BUILDING_A_CLI.md.