REFERENCE

CLI

Five commands. The CLI has no argument-parsing dependency, so flags are matched exactly as documented — an unrecognised argument prints usage rather than being ignored.

Running it

Terminal

npx cheela <command>

# or install it into the project
npm install -D @cheela/cli

cheela init writes scripts for the three you will use most:

package.json

{
  "scripts": {
    "dev": "cheela dev",
    "deploy": "cheela deploy",
    "status": "cheela status"
  }
}

Terminal

cheela --help    # or -h, or no arguments at all

cheela init

Scaffolds a project in the current directory. Takes no arguments.

Terminal

npx cheela init

PATH	CONTENTS
.cheela/runtime.ts	An empty Runtime, default-exported.
cheela.config.ts	A defineConfig call with apiKey wired to the environment, and commented placeholders for endpoint, website and adp.
package.json	Dependencies on @cheela/cli, @cheela/runtime and @cheela/sdk, plus the three scripts above.
.env.example	CHEELA_API_KEY.
.gitignore	Appends .env and .cheela/generate.cache.json if they are missing.

It never overwrites

A file that already exists is reported as ✓ Preserved rather than replaced, so running init in a populated directory is safe.

cheela dev

Prints the capability tree your runtime module registers. No network calls, no writes — this is the fast check that a registration compiles and resolves.

Terminal

npx cheela dev

Output

Cheela Runtime

Capabilities

catalog-search
  └─ search

order-status
  └─ lookup

✓ Runtime ready

cheela deploy

Runs the full pipeline and pushes a deployment. Requires CHEELA_API_KEY.

Terminal

npx cheela deploy
npx cheela deploy --dry-run

FLAG	EFFECT
--dry-run	Everything except the push. Generators still write their files, so this also regenerates artifacts on demand.

--dry-run is the only accepted argument. Anything else prints usage and exits non-zero.

Output reports, in order:

config loaded, runtime loaded, capability and action counts
each generator with its output path and one of created, updated, unchanged, skipped (cached)
a capability diff against what is currently live, when the two disagree
the new deployment version and status
a warning naming any capability published without an input schema

The schema warning is worth reading

A capability with no input schema is advertised to the model as taking no parameters. Legitimate for something nullary; a bug everywhere else.

Full walkthrough in Deploy a runtime.

cheela status

Reports what the control plane holds for this runtime, and diffs it against your local registrations. Requires CHEELA_API_KEY.

Terminal

npx cheela status

Output

Cheela Runtime

Runtime        rt_8f2a
Deployment     3
Status         active
Connection     online
Transport      http
Provider       openrouter
Model          ...

Capabilities   4, in sync

When they disagree, the diff is printed instead:

Output

Capabilities   out of sync with the deployment

  + catalog-search      (local, not deployed)
  - legacy-lookup       (deployed, not local)

Run `cheela deploy` to publish the current set.

Polling status doubles as the runtime’s check-in — it is what drives the online/offline indicator, so there is no separate call to wire up.

cheela manifest pull

Fetches the published capability manifest and writes it into the frontend that serves it.

Terminal

npx cheela manifest pull --runtime rt_8f2a
npx cheela manifest pull --runtime rt_8f2a --out static/.well-known/agent-discovery.json

FLAG	REQUIRED	DEFAULT
--runtime	yes	—
--out	no	public/.well-known/agent-discovery.json

This is the one command that needs no cheela.config.ts, no runtime module, and no credential. It runs in your frontend’s build, which frequently lives in a different repository from your capabilities.

Missing --runtime is an error, and the message tells you where to find the id.

See Publish a manifest.

Environment

.env is loaded from the project root before cheela.config.ts is evaluated, so your config reads populated values.

VARIABLE	USED BY	DEFAULT
CHEELA_API_KEY	deploy, status	— (required)

The project root is found by walking up from the working directory, so commands work from a subdirectory.

Exit codes

CODE	WHEN
0	The command succeeded, including a dry run.
1	Anything else: an unknown command, a missing required flag, invalid config, an unloadable runtime, or a failed request.

Errors are printed as ✗ message on stderr. Three of them name a specific fix rather than a symptom:

Unreachable control plane — check your network.
401 or 403 — CHEELA_API_KEY is invalid or does not belong to an active runtime.
Invalid config — every failing field is listed with its own message.