CAOS CLI

The CAOS CLI is the ergonomic developer front-end to the kernel’s API surface. It is one of the three ways metadata enters an org (alongside the raw API and installing a package), and — with the API it wraps — one of the only ways to change an org. Anything the CLI does, the API can do; the CLI exists for developer ergonomics, version-controlled workflows, and the local VS Code experience.

The CLI is a client of the API, not a second engine

Every command resolves to one or more API calls. caos deploy reads local source, diffs it against the target org, and calls the deploy API; caos query calls the Data API; caos describe calls the describe layer. There is no capability the CLI has that the API lacks, and no path into an org that bypasses the API’s validation and access checks. This matters for trust: a headless customer scripting against the raw API gets exactly the enforcement the CLI gets, because the CLI is an API client.

Reach for the CLI for interactive and version-controlled authoring; reach for the API directly for programmatic integration and headless automation. They are the same surface with two front doors.

The source / project format

An org’s metadata is representable on disk as source — the state that makes it diffable, reviewable, and deployable like code.

• Directory layout. Metadata is organized on disk by type (objects, fields, layouts, list views, apps, permission sets, page templates, packages, …), each type in its own tree, each component a file.
• Per-type file format. Components are authored as structured source (JSON), one component per file, validated against the type’s schema. The Schema Registry is the authority for what each type’s file may contain; caos schema emits those schemas so an editor gives intellisense against them.
• The manifest. A manifest declares what a given operation targets — the set of components to deploy or retrieve — so a deploy moves an intended set, not “whatever changed.”

Because the format is plain source in a repository, an org’s configuration is committed, branched, diffed, and reviewed with ordinary version-control tooling.

Deploy and retrieve — diff, validate, apply

The two core operations move metadata between an org and local source.

• Retrieve pulls an org’s metadata into the local source format.
• Deploy computes the difference between local source and the target org, validates it against the type schemas and referential integrity, and applies it in one transaction — idempotent, validated-before-apply, rolled back on failure. There is no “this type isn’t deployable” gap: all configuration is deployable metadata.

A deploy that would leave a dangling reference — a layout naming a missing field, an app naming a deleted theme — is rejected before anything applies, never silently stripped, and the rejection comes back both as a plain-English explanation and as a machine-readable object keyed by API names, so a person and a tool read the same failure. A pre-flight pass reports every problem at once (not one at a time) and can offer to pull in missing dependencies so the next run is whole.

The command surface

The CLI is an evolving surface — commands are added as they earn their place. The load-bearing ones:

Command	What it does
caos org login	Authenticate to an org (resolves to its tenant + instance; token/PAT auth).
caos org describe	Describe the connected org — its users and roles, apps, objects, and counts.
caos retrieve	Pull an org’s metadata into the local source format.
caos deploy	Push local metadata to a target org — diff, validate, apply transactionally.
caos diff	Show what a deploy would change, before running it.
caos describe <type> [api]	Describe a single component — an object’s fields, a layout’s regions, a user’s access — in human- or machine-readable form.
caos query	Run a Data API query (records) or a describe query (metadata-of-metadata) from the terminal.
caos schema	Emit the JSON Schemas that give an editor intellisense on metadata files.
caos package	Build, version, install, lock, and list packages.
caos provision	Create, configure, and retire orgs; install a feature set.

Package and provisioning commands drive the same Package Manager and Provisioning services the API exposes; they are grouped here as the developer’s entry point to them.

Two ways to deploy — visual or CLI

The CLI is the developer path; it is not the only one. A visual change-set editor offers the same deploy for admins — pick the components to move, and it pulls in their dependencies as the set is built, shows the diff against the target, and applies on approval, with no terminal required. Both paths run the identical validate-then-apply engine; only the front door differs, so the person who authors need not be the person who deploys.

Local VS Code tooling

A companion VS Code extension drives the CLI locally: org authentication, deploy-on-save, and schema-aware editing of metadata files (backed by caos schema). It is the CAOS analog of building against an org from a project in an IDE — author locally against the schemas, deploy to a dev org, iterate. The extension is a client of the CLI, which is a client of the API: one surface, three depths of ergonomics.