Getting started

This page walks the path from an empty org to your first deployed change. It uses the platform’s command-line tool and API; both are clients of the same validate-and-commit engine described in How the platform works.

1. Provision an org

An org is the tenant — the single container everything else lives in. Provisioning creates one from an org shape: a starter bundle that decides what a fresh org contains on day one (which packages install, what default metadata seeds, its region and home instance). A bare shape gives you the engine and nothing else; a “CRM” shape gives you a shell, setup, and a sales app already installed.

Provisioning hands back credentials quickly. You sign in almost immediately and land on the empty-workspace screen — the org before anything is installed — while any default packages finish installing in the background and populate the workspace.

The sign-in screen is one of the two surfaces the engine renders on its own, so it works before any package is installed. Authenticate, and the org resolves to your session. With no shell installed yet, you see the empty workspace; with a shell installed, you see its frame.

From here there are three ways to change the org. They all reach the same engine.

3a. The CLI

The CLI is the developer’s path — a client of the API with an on-disk source format, diffing, and schema-aware editing. Authenticate, pull the org’s current metadata into local source, make a change, and deploy it back:

caos org login               # authenticate to the org
caos metadata retrieve       # pull metadata into local source
# ...edit the source: add an object, a field, a layout...
caos metadata diff           # preview exactly what a deploy would change
caos metadata deploy         # validate + apply in one transaction

caos metadata deploy computes the difference between your local source and the org, validates it against the type schemas and referential integrity, and applies it atomically — or rejects it whole, with a plain-English explanation and a machine-readable object keyed by API names. Because the source is plain files in a repository, an org’s configuration is committed, branched, diffed, and reviewed like any other code. See the CLI reference on the architecture site for the full command surface.

3b. The API

If you are building headless — driving the org from your own front end and infrastructure — work directly against the API. It exposes record CRUD and query, metadata deploy and retrieve, fine-grained metadata operations, and an event stream. A first record write looks like:

POST /data/Account
Content-Type: application/json

{ "Name": "Northwind Traders", "Industry": "Retail" }

and a query:

GET /data/query?q=SELECT Id, Name FROM Account WHERE Industry = 'Retail'

Every call runs under your session and passes through the access engine, so the API enforces exactly the permissions the UI would. Nothing about the platform requires you to render its screens. The API families and their shapes are described on the architecture site’s API page.

3c. Install a package

The fastest way to a working system is to install packages rather than author from scratch. Installing a package is the same validate-and-commit operation, run over a versioned bundle and its capability registrations. Install a shell package and the org gets a header, navigation, and an app switcher; install setup and you get the administration surface; install an app and its objects, layouts, and tabs arrive together.

Because a package can claim a capability, installing one can change the whole frame — a different shell package produces a different-looking platform — while the engine underneath is unchanged.

Where to go next

The developer surface — the full map of what you can author, and where each part is documented.
How the platform works — the model behind these three paths.

The platform is under active construction. This guide documents the developer interface as it is being built; the architecture site is the settled specification the build follows.