@cef-ai/cli

cef — build, typegen, and inspect agents from the command line. Mirrors the Agent Runtime contract (ADR-001): bundles install a flat handler map at globalThis.__handlers, manifests carry the routing table the orchestrator reads.

Install

pnpm add -D @cef-ai/cli

This adds the cef binary to node_modules/.bin. In a workspace project, invoke it via pnpm exec cef <subcommand>.

Subcommands

cef build writes one directory per declared agent:

dist/
  <agentId>/
    bundle.js      # IIFE that installs globalThis.__handlers — a flat map
                   # of handler functions the runtime dispatches as
                   # __handlers[name](event, context). Event handlers are
                   # keyed "<engagementId>::<method>"; lifecycle hooks under
                   # the fixed keys onStart / onClose.
    manifest.json  # AgentManifest body — bundle embedded inline; each
                   # engagement carries handles{eventType -> handlerName}
                   # (namespaced) and hooks[] ("start"/"close"). Identity /
                   # signature fields are blank until `cef publish` signs.

The handler-name namespacing (<engagementId>::<method>) keeps the flat __handlers map collision-free when multiple engagements declare a method of the same name; the orchestrator returns these strings verbatim from HandlerFor, so AR looks them up directly. Lifecycle hooks are NOT namespaced — the orchestrator hardcodes onStart / onClose — so a method name may be reused as an event handler across engagements, but only one engagement per agent may own each lifecycle hook (cef build errors on a collision).

cef typegen reads cef.config.ts (and publishes declarations) and writes .cef/generated.d.ts, populating KnownEventTypes so authors get string-literal autocompletion on @OnEvent and ctx.publish. The cef.lock.json snapshot is rewritten on every run so VCS diffs surface typegen drift.

DDC credentials (cef push, cef widget push, cef cubby push)

Writes to the bucket are authorized by exactly one of:

• --secret-phrase / $CEF_DDC_SECRET_PHRASE — the phrase of the key that owns the bucket.
• --access-token / $CEF_DDC_ACCESS_TOKEN — a DDC access token granted by the bucket owner.

An access token either names no subject (a bearer token: sent as it is) or was issued to one key, its subject — the token in a ROC agent service invite is issued to the invited member. The storage node accepts a subject-bound token only on requests signed by that key, so the CLI needs its phrase too: --subject-phrase / $CEF_DDC_SUBJECT_PHRASE. The CLI checks that the phrase derives the subject (sr25519 or ed25519) before connecting, and refuses a subject-bound token without it rather than letting the node answer issuer doesn't match subject in parent token. Without that phrase, use "Copy DDC token for the CLI" on the agent service's Members panel in ROC — it signs, with your wallet, a token that names no subject beneath your invite — or ask the bucket owner for a token that names no subject.

Cubbies a pushed agent declares

A bucket push (cef push --bucket) also declares, in the bucket's cubby registry (cubbies/<alias>), every cubby the manifest carries that the registry does not name yet — at 0.1.0, the version cef cubby push uses, with the manifest's migrations. This is what ROC does on Deploy for the workflow runner's runs cubby; without it a workflow pushed only through the CLI fails at its first step with cubby: lookup schema: … Failed to get cns record. An alias the registry already names is never touched (change a declared schema with cef cubby push), and nothing is declared when the registry cannot be read. A declaration that fails to write fails the command after the agent was pushed; pushing again retries it. cef push --vault does not do this — vault-api does not declare cubbies either.

Quickstart

pnpm add -D @cef-ai/cli
pnpm exec cef build
pnpm exec cef inspect dist/<agentId>

Registering an agent that runs elsewhere is the same command with a different --kind, and needs no build step at all — there is no code of ours to compile:

pnpm exec cef push --kind external \
  --card https://ai.example/.well-known/agent-card.json \
  --bucket 1338 --as-pubkey 0x<agent-service-pubkey> --env dev

It appears in ROC's registry like any other agent, and can be connected to a vault and sent events from the sandbox.

Publishing into an organization vault

An organization vault's agents live in the vault's own registry bucket, and vault-api writes it — not the CLI. Name the vault and the scope to publish from instead of a bucket:

pnpm exec cef push --vault <vaultId> --vault-scope gtm \
  --secret-phrase "<your wallet phrase>" --as-pubkey 0x<agent-service-pubkey> --env dev

vault-api checks that you hold write on the scope (the vault owner, or a member with a member-level grant on it) and binds the agent's alias to the scope it is first published from, so another scope cannot replace it. The CLI uploads the version's files with the manifest unstamped; vault-api stamps the bundle and widget CIDs and returns the stored manifest, which cef push writes back to dist/<id>/manifest.json.

Credentials: --secret-phrase / $CEF_VAULT_SECRET_PHRASE signs with your own wallet key, derived as ed25519 (the only scheme vault-api accepts), or --vault-token / $CEF_VAULT_TOKEN sends a wallet-api token. $CEF_DDC_SECRET_PHRASE is not used here: it names a bucket owner, not you. --bucket, --access-token, --preset, --endpoint and --cdn do not apply and are refused.

A vault answers REGISTRY_NOT_CONFIGURED until its owner has recorded a registry bucket and sealed a registry delegation for it (PUT /api/v1/vaults/<vaultId>/delegations). The owner does that with "Enable agent publishing" on the organization page in ROC, or with sdk.vault.delegations.grant from @cef-ai/vault-sdk.

The kinds take disjoint flags — a bundle has no card, and a card has no dist/ — so passing one kind's flag with the other's --kind is refused by name rather than ignored. The failure it prevents is silent: --card without --kind external would otherwise push whatever was last built and report success.

Programmatic API

Every subcommand has a corresponding function exported from the package root, useful from tests and scripts:

import { cefBuild, cefTypegen, cefInspect } from "@cef-ai/cli";

const build = await cefBuild({ cwd: process.cwd(), outDir: "dist" });
for (const a of build.agents) {
  console.log(a.agentId, a.bundlePath, a.bundleBytes);
}

await cefTypegen({ configPath: "./cef.config.ts" });

const inspected = await cefInspect({
  agentDir: "dist/echo",
  print: false,
});
for (const e of inspected.engagements) {
  console.log(e.id, e.handles, e.hooks, e.exposedMethods, e.missingMethods);
}

Build-time lints

cef build runs a syntactic lint pass over the agent's entry file before bundling. Failures abort the build with a single, actionable message. The rules mirror those in @cef-ai/eslint-plugin so editor warnings agree with CI failures.

• @OnEvent(...) argument must be a string literal.
• ctx.publish(t, ...) first argument must be a string literal.
• ctx.cubby("alias") argument must be a literal AND a declared alias in cef.config.ts cubbies[].alias.
• ctx.models.X member must reference a declared model alias.
• Imports must not target the banned module list (Node built-ins like fs, net, http, child_process, plus sync DB / network npm packages). Agents use the global fetch for HTTP and ctx.cubby for state; globalThis.crypto (WebCrypto) replaces node:crypto.

The full banned-module list and rationale live in agent-sdk.md §7.

Companion packages

• @cef-ai/agent-sdk — the decorators, Context, and defineAgent consumed by the agent code being built.
• @cef-ai/testing — simulator harness used by cef test once it lands.
• @cef-ai/eslint-plugin — editor-time lints that match the build-time enforcement.

References

• Agent SDK spec: ../../../company-memory-bank/specs/platform/03-components/agent-sdk.md
• Runtime integration contract: ../../../company-memory-bank/specs/platform/03-components/sdk-runtime-integration-contract.md

The ../company-memory-bank/... paths point at an internal sibling repo and are not browsable from a fresh clone.