CLI (@cef-ai/cli)
The reference section is the lookup layer: every CLI command, SDK export, limit, error code, and term. Start with the CLI.
npm install -D @cef-ai/cli@2.8.0 # or: npm i -g @cef-ai/clicef --version| Command | Does |
|---|---|
cef init |
Scaffold a project. |
cef build |
Bundle agents and write manifests. |
cef typegen |
Generate types for declared models and peers. |
cef inspect |
Check a built agent. |
cef push |
Upload an agent version, or register an A2A agent you run elsewhere. |
cef widget push |
Publish a service widget. |
cef cubby push |
Publish the service’s cubby declarations. |
cef deploy |
Apply deployment records. |
cef dev |
Serve a widget locally. |
cef publish |
Send the agent card to the marketplace listing. |
cef eval |
Workflow evaluations. |
cef test |
Not implemented; prints a notice. Run vitest directly. |
Any failing command prints its error and exits with code 1.
Environments
--env dev|stage|prod, or $CEF_ENV. Default dev.
--env |
DDC network (--preset) |
|---|---|
dev |
DEVNET |
stage |
TESTNET |
prod |
MAINNET |
The environment also selects the platform API for deploy, the marketplace for publish, and the endpoints written into widgets. Specific flags (--preset, --endpoint, --marketplace) override single values.
Credentials
| Variable | Flag | Used by |
|---|---|---|
CEF_DDC_ACCESS_TOKEN |
--access-token |
push, widget push, cubby push: a DDC token from ROC (Settings → Access → DDC access token). |
CEF_DDC_SECRET_PHRASE |
--secret-phrase |
Same commands: the bucket owner’s sr25519 phrase, instead of a token. |
CEF_DDC_SUBJECT_PHRASE |
--subject-phrase |
The phrase of the key a token was issued to, when the token names one. |
CEF_ACCESS_TOKEN |
--access-token |
deploy, publish, eval run: the CLI access token from ROC (Settings → Access → CLI access token). |
CEF_VAULT_TOKEN |
--vault-token |
push --vault. |
CEF_VAULT_SECRET_PHRASE |
--secret-phrase |
push --vault: your wallet phrase (used as ed25519). |
CEF_ENDPOINT |
--endpoint |
deploy: platform API base URL. |
CEF_MARKETPLACE_URL |
--marketplace |
publish. |
Prefer environment variables to flags: a secret on the command line stays in shell history and is visible in the process list. A push needs exactly one of a phrase or a token.
cef init
cef init [dir]Scaffolds a hello-world agent: cef.config.ts, src/agent.ts, migrations/, deployments/, a widget, a test, and, unless --no-ai, AGENTS.md, CLAUDE.md, and .claude/.
| Flag | Default | Meaning |
|---|---|---|
--name <alias> |
slug of the directory | Agent alias. |
-y, --yes |
— | Accept all defaults. |
--pm <manager> |
— | pnpm, npm, yarn, or bun. |
--install |
off | Install dependencies. |
--no-git |
— | Skip git init. |
--no-ai |
— | Skip the AI assistant files. |
--force |
— | Scaffold into a non-empty directory. |
--template <name> |
hello-world |
Template. |
cef build
Bundles every agent in cef.config.ts and writes dist/<alias>/bundle.js, manifest.json, and widgets/<id>/ (runtime vendored and manifest injected).
| Flag | Default | Meaning |
|---|---|---|
--config <path> |
cef.config.ts |
Config file. |
--out <dir> |
dist |
Output directory. |
--env <env> |
dev |
Endpoints written into widget manifests. |
--as-pubkey <hex> |
— | Agent Service pubkey written into widget manifests’ agent id. |
Build checks are listed in Write an agent.
cef typegen
Fetches each declared model’s model.json and each peer in uses, then writes .cef/generated.d.ts and cef.lock.json.
| Flag | Default | Meaning |
|---|---|---|
--config <path> |
cef.config.ts |
Config file. |
cef inspect
cef inspect dist/<alias>Prints each engagement and checks that the bundle exports every handler the manifest routes to. Exits with code 2 when a handler is missing, so you can run it in CI.
cef push
Uploads the built agent in dist/ to a bucket you can write, or through vault-api into an organization vault, or registers an A2A agent you run elsewhere (--kind external).
cef push --bucket <bucketId> --as-pubkey <agentServicePubkey>cef push --vault <vaultId> --vault-scope <scope>cef push --kind external --card <url> --bucket <bucketId> --as-pubkey <agentServicePubkey>| Flag | Applies to | Default | Meaning |
|---|---|---|---|
--kind <kind> |
all | internal |
internal pushes the bundle in dist/; external registers an A2A agent. |
--bucket <id> |
bucket push, external | — | DDC bucket id (decimal). |
--as-pubkey <hex> |
all | config value | Agent Service pubkey; forms the agent id <pubkey>:<alias>. |
--agent <id> |
internal | the only built agent | Which dist/<id>/ to push. |
--out <dir> |
internal | dist |
Build output directory. |
--vault <vaultId> |
internal | — | Publish into this organization vault through vault-api. Needs --vault-scope. |
--vault-scope <scope> |
--vault |
— | Scope to publish from. The alias is bound to the scope it is first published from. |
--vault-api <url> |
--vault |
environment’s vault API | vault-api base URL. |
--vault-token <token> |
--vault |
$CEF_VAULT_TOKEN |
Wallet-api bearer token. |
--card <url> |
external (required) | — | A2A Agent Card URL. A bare origin gets /.well-known/agent-card.json. |
--alias <name> |
external | slug of the card name | Registry alias; no :. |
--agent-version <semver> |
external | 1.0.0 |
Version to register. |
--scope <name...> |
external | default |
Scopes the agent asks for. |
--idle-timeout <duration> |
external | 30m |
How long a conversation survives without events. 0 is refused. |
--secret-phrase <phrase> |
all | env | Bucket owner’s phrase, or with --vault your wallet’s phrase. |
--access-token <token> |
bucket push, external | $CEF_DDC_ACCESS_TOKEN |
DDC access token. |
--subject-phrase <phrase> |
bucket push, external | $CEF_DDC_SUBJECT_PHRASE |
Phrase for a token that names a subject. |
--env <env> |
all | dev |
Environment. |
--endpoint <url> |
bucket push, external | from --env |
DDC blockchain endpoint. |
--preset <name> |
bucket push, external | from --env |
MAINNET, TESTNET, or DEVNET. |
--cdn <url> |
bucket push, external | from preset | CDN endpoint. |
A flag that belongs to the other kind or destination is refused by name rather than ignored. Before uploading with a token, cef push checks that the token chains to the bucket’s on-chain owner and that it has not expired; see Team.
On success it prints the agent id, bucket, bundle CID, manifest CID, version CID, uploaded widgets, and the cubbies it declared.
cef widget push
Publishes a built widget subproject under the bucket’s widgets root. Run it in the widget’s directory after its own build.
| Flag | Default | Meaning |
|---|---|---|
--bucket <id> |
required | DDC bucket id. |
--dir <path> |
current directory | The widget subproject. |
--out <dir> |
dist |
Build output within it. |
--widget-id <id> |
cef.id or package name |
Registry id. |
--widget-version <semver> |
package version | Version. |
--as-pubkey <hex> |
— | Agent Service the widget belongs to; written into the entry as <pubkey>:<id>. |
--secret-phrase, --access-token, --subject-phrase |
env | Credentials. |
--env, --endpoint, --preset, --cdn |
from --env |
Network and endpoints written into the widget. |
The cef block of package.json declares the widget (id, name, entry, scope, cubbyAlias, queries, events, kind, config). See Build a widget.
cef cubby push
Publishes cubbies/<alias>/*.sql declarations to the bucket. Creates no database: the platform applies them the first time an agent touches the cubby in a vault.
| Flag | Default | Meaning |
|---|---|---|
--bucket <id> |
required | DDC bucket id. |
--dir <path> |
./cubbies |
One subdirectory per cubby. |
--alias <name> |
all | Push only this cubby. |
--cubby-version <semver> |
0.1.0 |
Version for each declaration. |
--secret-phrase, --access-token, --subject-phrase |
env | Credentials. |
--env, --endpoint, --preset, --cdn |
from --env |
Network. |
See Cubby schema and migrations.
cef deploy
Applies every record in deployments/ as one set: PUT /api/v1/agents/<agentId>/deployments.
| Flag | Default | Meaning |
|---|---|---|
--env <env> |
dev |
Environment. |
--endpoint <url> |
$CEF_ENDPOINT, then from --env |
Platform API. |
--agent <id> |
the only built agent | Which dist/<id>/ to read identity from. |
--as-pubkey <hex> |
manifest value | Agent Service pubkey. |
--access-token <token> |
$CEF_ACCESS_TOKEN |
CLI access token. |
--version <v> |
— | Override version in every record (latest allowed). |
--deployments <path> |
deployments |
A folder, or one file holding a set or a record. |
--out <dir> |
dist |
Build output. |
--author <who> |
git user.email |
Audit author. |
--note <text> |
— | Audit note. |
--dry-run |
— | Print the set without applying it. |
--header <k:v> |
— | Extra request header; repeatable. |
Record format: Push and deploy.
cef dev
cef dev [widgetId] --as-pubkey <agentServicePubkey>Serves a widget from cef.config.ts with the runtime injected, and reloads the browser on change.
| Flag | Default | Meaning |
|---|---|---|
[widgetId] |
first declared widget | Widget to serve. |
--config <path> |
cef.config.ts |
Config file. |
--port <n> |
a free port | Listen port (0–65535). |
--host <host> |
127.0.0.1 |
Listen host. |
--env <env> |
dev |
Endpoints written into the manifest. |
--as-pubkey <hex> |
— | Needed for connectAgent() and query(). |
--no-watch |
— | Do not watch for changes. |
cef publish
Sends the agent’s card (not its manifest) to the marketplace listing. Not needed to deploy, connect, or run an agent.
| Flag | Default | Meaning |
|---|---|---|
--env <env> |
dev |
Environment. |
--marketplace <url> |
$CEF_MARKETPLACE_URL, then from --env |
Marketplace base URL. |
--agent <id> |
the only built agent | Which dist/<id>/. |
--out <dir> |
dist |
Build output. |
--as-pubkey <hex> |
config value | Agent Service pubkey. |
--access-token <token> |
$CEF_ACCESS_TOKEN |
CLI access token. |
cef eval
Workflow evaluations: datasets, experiments, comparisons. Subcommands: datasets, create <dataset>, pull <dataset>, push <dataset>, run <dataset>, experiments [dataset], compare <base> <candidate>, migrate. Flags and usage: Eval reference and Experiments.