Providers

A provider maps an external service API onto the command surface. An agent that has learned one provider can use every other one. The grammar, the flags, the JSON envelope, and the safety metadata are the same, whatever service is exposed.

What ships

Three tiers

Tier is a property of the directory a provider lives in. The provider does not declare it. The provider index is generated at build time by scanning those directories, so adding a provider in any tier is creating a directory. Nothing in package.json or the framework's source changes.

Writing a provider

It takes little effort when a coding agent does the work. Start with the platform's API specification. Most SaaS APIs publish a machine-readable description, and a provider is a mechanical mapping of that description onto the command surface: entities become topics, operations become commands, the specification's field types become flags, and its example values become fixtures. That is work a coding agent does well.

The repository's AGENTS.md is the guide written for such an agent. PROVIDER_AUTHORING.md includes a sample generation prompt to copy, with the provider's name, tier, spec file, and auth scheme to fill in. The repository also ships an add-provider skill for Claude Code that follows the same steps. The coding agent generates the provider and runs the conformance suite.

The author checks the credential schema, the safety metadata, and the error hints, writes the setup document, and opens the pull request.

A provider directory holds a provider definition, a credential schema, a client, an error classifier, metadata for learn, and its commands. From the credential schema, the framework derives the auth flags, the environment variable names, the profile format, and the status discover reports. From each command's declared metadata it derives policy enforcement, --dry-run and --confirm behavior, and the introspection output.

npm run scaffold-provider -- --tier contributed --name acme --display "Acme Widgets"
npm run build && npx vitest run test/conformance

The conformance suite iterates every registered command and checks, among other things: complete and truthful safety metadata, examples that name nothing internal, error hints that name the command fixing the problem, a working --schema and --examples with an empty environment, and no imports between providers or from core into a provider directory. The full guide, with the pull-request checklist, is PROVIDER_AUTHORING.md. In a CLI built on the framework the same suite runs from aclif/testing with npm test. See Build a CLI.

Tenant catalogs

An instance is one deployment of a platform, such as a single Salesforce org, with its own credentials and its own customizations. The word tenant, as in tenant catalog, means the same thing. A provider covers the platform's API as the vendor documents it. Every instance then adds custom objects, custom fields on standard objects, its own picklist values, and sometimes endpoints of its own, and none of that is in any specification. aclif learns it from the instance itself, at deploy time, with no change to the provider and no rebuild.

aclif <provider> introspect --bootstrap walks the instance once, under the operator's credentials, and records each custom entity and each custom field on a standard entity, with its type, label, enumerated values, and the entities it references. The walk is read-only and the catalog holds structure only, never record values or secrets. It is cached per provider and instance, so two Salesforce orgs get two catalogs, and each entry records how it was learned: from the platform's metadata API, inferred from a sample record, or found by a probe. --refresh recaptures after the instance changes and --all widens the walk to every entity. Once the catalog exists, learn lists the instance's own entities in its briefing and --schema reports them as available entities, with no further API call.

Canonical names

A canonical name is one name for an entity that each provider and instance calls something different. customer is Account in one Salesforce instance, Customer__c in a second, and core_company in ServiceNow. An alias set is the JSON or YAML file that records those mappings, for the entity and for the fields under it. A starter vocabulary ships with the framework, covering customers, contacts, people, opportunities, incidents, email, calendar events, and envelopes across the built-in providers.

An organization writes its own alias set from the tenant catalogs, one per instance, and the framework resolves it. Comparing two catalogs is how a person or an authoring tool decides that this instance's Account and that one's Customer__c are both customer. aliases validate checks the file's structure and that every provider it names is one the CLI has, and aliases import puts it in use, layered above the starter vocabulary so the organization's own mapping takes precedence. A command run with --canonical resolves each name for its provider and instance, sends the native names to the API, and records what it resolved in the envelope. An unknown canonical name exits 2 with the nearest matches. The native names stay reachable throughout. The formats are in CONTRACT.md.

Manifests

A declarative JSON manifest turns one HTTP endpoint, such as an Apex REST class or a ServiceNow scripted API, into a command with the same envelope, metadata, and introspection as a static one, without writing a provider. Manifests are loaded from the config directory standalone, or supplied by the host when embedded.