deploy-sdk

CLI for deploying CEF AI agent topologies from the command line. Create and manage agent services, then sync engagements, agents, cubbies, workspaces, streams, deployments, and rafts from a single YAML config. You can deploy, check status, clone an existing service into a directory, and delete entities—all from the terminal.

Requirements: Node.js 18+

Install

# Global install
npm install -g @cef-ai/deploy-sdk

# Run without installing
npx @cef-ai/deploy-sdk --help

# From repo (development)
npm install && npm run build
node dist/cli.js --help
# or: npx tsx src/cli.ts --help

Help and version

Everything the CLI accepts is documented in --help:

cef-deploy --help
cef-deploy -h
cef-deploy --version
cef-deploy -V

Environment variables

The CLI loads .env from the directory of your config file (or from --output-dir for clone). Create .env next to cef.config.yaml (or in the directory you pass to --output-dir).

| Variable | Required? | Used for | |----------|----------|----------| | CEF_AUTH_TOKEN | Yes (all API commands) | Bearer token for orchestrator and ROB. Use the same JWT as the ROB UI. | | CEF_ORCHESTRATOR_URL | Yes (deploy, status, clone, delete) | Orchestrator base URL (e.g. https://compute-1.devnet.ddc-dragon.com/orchestrator). | | CEF_ROB_API_URL | Yes for services, create-service, and when deploy creates workspaces or registers cubbies | ROB API base URL (e.g. https://api.rob.dev.cere.io/rms-node-backend). | | CEF_DDC_URL | Yes only when deploying cubbies | DDC/agent URL for cubby and cubby query create/update. | | CEF_ROB_ORIGIN | No | Override Origin/Referer for ROB. Auto-detected from CEF_ROB_API_URL if unset. |

Example .env:

CEF_AUTH_TOKEN=your-bearer-token
CEF_ORCHESTRATOR_URL=https://compute-1.devnet.ddc-dragon.com/orchestrator
CEF_ROB_API_URL=https://api.rob.dev.cere.io/rms-node-backend
CEF_DDC_URL=https://compute-1.devnet.ddc-dragon.com/agent

Copy from example/.env.example and edit.

Commands overview

| Command | What it does | |---------|----------------| | deploy (default) | Reads cef.config.yaml, creates or updates engagements, agents, cubbies, workspaces, streams, deployments, and rafts on the orchestrator. Writes returned IDs back into the config. | | status | Compares local config with deployed state. Reports each entity as up-to-date, outdated, not-deployed, or not-found. | | services | Lists agent services from ROB. Use this to get agentServicePubKey (and agentServiceId) for your config. No config file required. | | create-service | Creates a new agent service on ROB and the orchestrator. Returns agentServicePubKey and agentServiceId to put in your config. | | clone | Downloads an existing agent service into a directory: writes cef.config.yaml and engagement/agent/cubby/raft code files. | | delete | Deletes deployed entities from the orchestrator in reverse dependency order and removes their IDs from the config. Asks for confirmation unless --force. |

Options reference (all commands)

| Option | Applies to | Description | |--------|------------|-------------| | --config <path> | All | Config file path. Default: ./cef.config.yaml. For clone, also used to read agentServicePubKey if --pubkey is omitted. | | --dry-run | deploy | Show planned create/update operations only; do not call the API. | | --only <type> | deploy, delete | Act on only one entity type. Allowed: engagement, agent, cubby, workspace, stream, deployment, raft. | | --pubkey <key> | clone | Agent service public key (0x...). Required unless --config points to an existing config that has agentServicePubKey. | | --output-dir <dir> | clone | Directory to write cloned files into. Default: directory of --config. | | --force | clone, delete | Clone: overwrite existing files. Delete: skip confirmation prompt. | | --name <name> | create-service | Name of the new agent service (required). | | --bucket-id <id> | create-service | DDC bucket ID for the orchestrator. Optional; default: 0. | | -h, --help | All | Show full help. | | -V, --version | All | Show version. |

Command details

deploy (default)

Reads cef.config.yaml, creates or updates each entity type on the orchestrator, and writes returned IDs back into the config.

Options: --config, --dry-run, --only <type>

Examples:

cef-deploy
cef-deploy deploy
cef-deploy deploy --config ./app/cef.config.yaml
cef-deploy deploy --dry-run
cef-deploy deploy --only agent
cef-deploy deploy --only engagement
cef-deploy deploy --only cubby
cef-deploy deploy --only workspace
cef-deploy deploy --only stream
cef-deploy deploy --only deployment
cef-deploy deploy --only raft

Notes:

• Stale ID detection: If you copy a config from another agent service and change agentServicePubKey, the CLI may detect that stored IDs no longer match. It will prompt to clear entity IDs so everything deploys fresh.
• Crash recovery: IDs are written back after each entity type completes, so a partial deploy still records what was created.
• Workspaces are registered on ROB first, then provisioned on the orchestrator. agentServiceId is resolved from agentServicePubKey automatically.

status

Compares local config with what is deployed. Reports each entity as up-to-date, outdated, not-deployed, or not-found.

Options: --config

Examples:

cef-deploy status
cef-deploy status --config ./app/cef.config.yaml

services

Lists all agent services registered on ROB. Output includes agentServiceId, agentServicePubKey, and creation date. No config file is required; .env is loaded from the current directory or from the directory of --config if provided.

Options: --config (only to choose where to load .env from)

Examples:

cef-deploy services
cef-deploy services --config ./my-agent/cef.config.yaml

create-service

Creates a new agent service on both ROB and the orchestrator. Returns agentServicePubKey and agentServiceId to use in your cef.config.yaml.

Options: --name (required), --bucket-id (optional)

Examples:

cef-deploy create-service --name my-agent
cef-deploy create-service --name my-agent --bucket-id 1505

clone

Downloads an existing agent service into a directory: writes cef.config.yaml with all entity definitions and IDs, plus engagement files, agent task files, cubby query files (if CEF_DDC_URL is set), and workspace/stream/deployment structure from the ontology.

Requires: CEF_AUTH_TOKEN, CEF_ORCHESTRATOR_URL, and either --pubkey or a config file (via --config) that contains agentServicePubKey.

Options: --config, --pubkey, --output-dir, --force

Examples:

cef-deploy clone --pubkey 0x... --output-dir ./my-agent
cef-deploy clone --pubkey 0x... --output-dir ./my-agent --force
cef-deploy clone --config ./other/cef.config.yaml

Notes:

• Without --force, existing files are not overwritten (including cef.config.yaml).
• .env is loaded from --output-dir (or from the directory of --config). You can run deploy and status from the cloned directory afterward.

delete

Deletes deployed entities from the orchestrator in reverse dependency order: deployments → rafts → streams → workspaces → agents → engagements. After deletion, entity IDs are removed from cef.config.yaml.

Options: --config, --only <type>, --force

Examples:

cef-deploy delete
cef-deploy delete --config ./app/cef.config.yaml
cef-deploy delete --only agent
cef-deploy delete --only engagement
cef-deploy delete --only workspace
cef-deploy delete --only stream
cef-deploy delete --only deployment
cef-deploy delete --only raft
cef-deploy delete --force

Notes:

• The CLI shows a summary and asks for confirmation before proceeding. Use --force to skip the prompt (e.g. in CI).
• Cubbies cannot be deleted via the CLI (DDC limitation). The CLI warns about cubbies that have a cubbyId and suggests manual removal.

Config file (cef.config.yaml)

By default the CLI uses ./cef.config.yaml. Get agentServicePubKey from cef-deploy services or cef-deploy create-service.

Minimal structure:

agentServicePubKey: "0x..."

workspaces:
  - name: "Main Workspace"
    description: ""
    streams:
      - name: "Events Stream"
        description: ""
        selectors:
          - name: "all"
            conditions: ["*"]
        deployments:
          - name: "Main Deployment"
            description: ""
            engagement: "My Engagement"
            isActive: true
            triggers:
              - name: "all-events"
                conditions: ["*"]
        rafts:
          - name: "Data Ledger"
            description: ""
            file: "./rafts/ledger.ts"

engagements:
  - name: "My Engagement"
    description: ""
    file: "./engagements/engagement.ts"
    version: "1.0.0"

agents:
  - name: "Object Detection"
    alias: "objectDetection"
    description: ""
    version: "1.0.0"
    tasks:
      - name: "YOLO"
        alias: "yolo"
        file: "./agents/object-detection/tasks/yolo.ts"
        parameters: { properties: {}, type: "object" }

cubbies:
  - name: "syncMission"
    description: ""
    dataTypes: ["json", "search"]
    queries:
      - name: "syncMission"
        file: "./queries/syncMission.ts"
        parameters: { properties: {}, type: "object" }

• When parameters or returns are omitted, they default to { properties: {}, type: "object" }.
• Rafts are defined under streams. A raft file must export onInit(), onData(), query(), and onCleanup().
• A full reference config is in the example/ directory.

ID writeback

When the CLI creates an entity it writes the returned ID back into cef.config.yaml:

• engagementId, agentId, workspaceId, streamId, deploymentId, raftId, cubbyId

On the next run it will update that entity instead of creating a new one. Commit the updated config after deploy. Cubby queries are identified by name and do not get an ID written back.

Typical workflow

# 1. Create a new agent service
cef-deploy create-service --name my-agent
# Note agentServicePubKey and agentServiceId from output

# 2. Set up project
mkdir my-agent && cd my-agent
# Create .env with CEF_AUTH_TOKEN, CEF_ORCHESTRATOR_URL, CEF_ROB_API_URL
# Create cef.config.yaml with the pubkey and your entity definitions

# 3. Deploy
cef-deploy deploy

# 4. Check status
cef-deploy status

# 5. Change config or code, then redeploy
cef-deploy deploy

# 6. Clone to another directory (e.g. for a teammate)
cef-deploy clone --pubkey 0x... --output-dir ../my-agent-copy

# 7. Clean up
cef-deploy delete

Tests

npm test                  # unit tests
npm run test:integration  # optional: reachability check
npm run test:e2e          # optional: real orchestrator/ROB (loads .env.e2e)

For e2e: copy .env.e2e.example to .env.e2e (gitignored) and set the required variables. The e2e suite can create a fresh agent service per run when CEF_ROB_API_URL is set.