Install the CLI

You can build and run a workflow entirely in ROC, with nothing installed. Install the CLI and SDKs when you want code: code agents, workflows in code, your own app talking to a vault, tests, and evaluations.

Prerequisites

Node.js and a package manager. Examples use npm; pnpm, yarn, and bun work the same way.
TypeScript for agents. Engagements use decorators (@Engagement, @OnEvent).

The packages

Package	Version	Kind	Use it for
`@cef-ai/cli` (`cef`)	2.8.0	dev	Scaffold, build, push, and deploy agents and workflows; push service cubbies and widgets; run evaluations.
`@cef-ai/agent-sdk`	5.8.0	runtime	Code agents (`@Engagement`, `@OnEvent`, `ctx`), `defineAgent` and `defineWorkflow` for `cef.config.ts`.
`@cef-ai/vault-sdk`	5.5.0	runtime	Your own apps and servers talking to a vault. Not for agent code.
`@cef-ai/widget-runtime`	2.4.1	runtime	The browser half of a widget. The CLI vendors it into built widgets.
`@cef-ai/testing`	3.3.5	dev	Run your agent against an in-process fake platform in your own test runner.
`@cef-ai/eval`	0.1.0	dev	Datasets, experiments, and results for workflows.
`@cef-ai/eslint-plugin`	1.0.0	dev	Editor rules that match the CLI’s build checks.

Install for building agents and workflows in code

Start a project with the scaffold:

npx @cef-ai/cli@2.8.0 init my-agent

cef init [dir] writes a project with a config, an engagement, a cubby migration, a widget, a test, and AI-assistant files (AGENTS.md, CLAUDE.md). Options: --name <alias>, --pm <npm|pnpm|yarn|bun>, --install, --no-git, --no-ai, -y. Set the scaffold’s @cef-ai/* dependencies to the versions in the table above.

Or add the packages to an existing project:

npm install @cef-ai/agent-sdk@5.8.0
npm install -D @cef-ai/cli@2.8.0 @cef-ai/testing@3.3.5 @cef-ai/eslint-plugin@1.0.0

The CLI is a dev dependency; run it with npx cef … or an npm script.

Install for an app that talks to a vault

npm install @cef-ai/vault-sdk@5.5.0

The package is an ES module and runs in the browser and in Node. See Work with the Vault SDK.

Install for workflow evaluations

npm install -D @cef-ai/eval@0.1.0

cef eval uses the same library. See Evaluations.

Verify

npx cef --help

A list of commands (init, build, typegen, inspect, push, publish, deploy, dev, widget, cubby, eval) means the CLI is installed.

Credentials

The CLI talks to two places, with two kinds of credential:

For	Credential	Set with
`cef push`, `cef widget push`, `cef cubby push` (writing to your Agent Service’s storage bucket)	The bucket owner’s secret phrase, or an access token the owner granted you	`CEF_DDC_SECRET_PHRASE`, or `CEF_DDC_ACCESS_TOKEN`
`cef deploy`, `cef publish`	A CLI access token minted in ROC	`CEF_ACCESS_TOKEN`

Each has a matching command-line flag, but a secret on the command line stays in your shell history; prefer the environment variables. --env <dev|stage|prod> (or CEF_ENV) picks the network. See Push and deploy and the CLI reference.

Pin your versions

Pin exact versions. Check the current one before upgrading:

npm view @cef-ai/cli version

Next steps

Quickstart: build and run a workflow
Write an agent
Workflows in code