Controller AI CLI

Build, test, and operate Controller AI workflows and agents from the coding agent you already use.

Beta. The CLI is new and moving fast: releases are frequent, and each one carries fixes the managed skills assume. cai doctor tells you (and your coding agent) the moment an upgrade or skill update is available — treat that as part of setup, not optional. Something broken or missing? Tell us at [email protected].

Install and connect

Node.js 20 or newer is required. Use the durable setup command:

npm install -g @controllerai/cli && cai connect

cai connect fetches and verifies the current Agent Skills. When the hosted source is unavailable, it retains an intact current or newer managed set and installs the bundled version only where skills are missing, older, or broken. Invalid manifests, incompatible versions, unsafe redirects, and integrity failures stop setup instead of silently falling back. It then opens browser authorization and verifies the credential and API connection. Its final output includes the exact controllerai-start/SKILL.md path the current coding-agent session should read. Running npx @controllerai/cli connect is useful for a trial, but it does not guarantee that the cai binary remains available after that process exits.

On a remote or headless machine, run cai connect --no-open. Open the printed authorization URL in any browser and leave the terminal running until approval completes. Linux sessions without a desktop display use this manual path automatically.

The browser flow stores a revocable cai_ credential in ~/.config/cai/config.json with owner-only permissions. It receives the full CLI capability set displayed on the approval screen; narrower scope selection is not available yet. A CLI credential cannot mint a legacy API key.

Start building

For an agent, first decide whether each capability is one ready integration action or needs a workflow. A direct action does not require workflow context:

cai integration search "send a Slack message" --agent-attachable
cai integration actions --integration <integrationSlug> "send message" --agent-attachable
cai integration action --integration <integrationSlug> --key <actionKey>
cai connection list --integration <integrationSlug>
cai connection connect <integrationSlug> --wait
cai agent create --name "Support agent" --instructions-file instructions.md
cai agent add-action <agentId> \
  --integration <integrationSlug> \
  --action <actionKey> \
  --connection <connectionId>
cai agent tools <agentId>

integration search includes provider integrations and native workflow actions in one server-ranked list. integration actions <query> uses the catalog's global relevance order; add --integration <slug> to list or narrow one integration. Add --agent-attachable to either discovery command when selecting a direct agent action. The exact action detail reports whether the action is attachable and, for a native registry action, whether it needs a connection; omit the connection steps and agent add-action --connection when it does not.

Ready actions run without per-call approval by default. Add --require-confirmation when the operation sends communications, writes or deletes data, changes permissions, or can incur spend. Make this a deliberate per-action decision.

Use a workflow when the behavior needs multiple steps, transformations, branches, loops, triggers, durable data, or a custom typed contract:

cai workflow list
cai workflow create --name "Lead intake"
cai use <workflowId>
cai integration actions "send a Slack message"
cai integration action --integration <nodeSlug> --key <nodeKey>
cai node init --flow <flowId> --node <nodeSlug> --key <nodeKey>
cai node status <nodeId>

For expressions, use the guarded write path. It reads prop metadata, compiles against the real node context, lets the backend select the correct storage field, and verifies the persisted expression:

cai expr ops --workflow <workflowId> --type text
cai expr context <nodeId> --prop <prop>
cai expr set <nodeId> --prop <prop> --js '<expression>'

expr ops is workflow-scoped; a prior cai use <workflowId> or CAI_WORKFLOW selection may replace its explicit --workflow flag.

Test before publishing:

cai run node <nodeId> --inputs values.json
cai run flow <flowId> --inputs values.json
cai workflow publish

Agent Test and Live modes are separate:

| | Test / draft | Live / shared | | --- | --- | --- | | Agent | Current mutable draft; owner only | Latest published immutable version; shared users never see draft | | Workflow tools | Current development heads | Each workflow's latest live release | | Reference files | Current draft knowledge | Knowledge frozen at agent publish | | Runtime files | Live files overlaid by development/test files at the same path | Current live files only |

Publishing an agent snapshots its name, instructions, tool identities, descriptions and approval policies, and knowledge files, then moves existing live conversations to that version. To update those fields in Live: edit the draft, verify Test, publish the agent, and verify Live.

Workflow releases are not pinned to agent versions. Publishing an attached workflow changes every live agent that follows it without another agent publish. A direct action's connection and authorization grant are live security bindings: rebinding can redirect Live, while breakage, revocation, or detachment can block Live immediately without another agent publish. Detachment also changes the draft tool list; publish afterward to remove that unavailable tool from the published list.

Direct actions run inline in the hosted conversation; they do not create workflow execution IDs:

cai agent create --name "Support agent" --instructions-file instructions.md
cai agent add-action <agentId> --integration <slug> --action <key> --connection <id>
# Or, for orchestrated behavior:
cai agent add-workflow <agentId> --workflow-id <workflowId> --flow <flowId>
cai agent test <agentId> --draft --message "Handle this sample request"
cai workflow status
cai workflow publish --name "Support workflow v1"
cai agent publish-preflight <agentId>
cai agent publish <agentId>
cai agent test <agentId> --live --message "Handle this sample request"

Skip the workflow publish when live already matches the tested development state, and skip it entirely for an agent with only direct actions. Publishing a workflow already used by another live agent changes that agent immediately.

Organization-shared agents run direct actions through the agent owner's connected external account. Controller AI usage draws from the organization's shared usage pool. The connection is live-bound: rebinding or revoking it can immediately affect a published agent, and detaching the grant can block the published tool before the agent is republished.

Use cai <command> --help for the complete command surface and --json for a stable machine-readable envelope.

Skill targets

cai skills update verifies the hosted manifest, file sizes, and SHA-256 digests before replacing any managed copy. cai skills status reports current, stale, modified, incomplete, and unmanaged installations. cai skills install uses the offline copy bundled with the installed CLI.

Skill commands auto-detect installed hosts. Explicit targets include agents, codex, claude, cursor, copilot, all, and the open-standard project location .agents/skills via --target project. Codex and the generic Agent Skills target use $CODEX_HOME/skills (default ~/.codex/skills) and ~/.agents/skills, respectively; Claude uses ~/.claude/skills.

The installer replaces only Controller-AI-managed copies by default. It refuses to overwrite an unmanaged folder with the same skill name unless --force is explicitly supplied. Skill-set versions are immutable: changing source bytes requires a version bump, and both the build and runtime installers reject different contents that claim an existing version.

Configuration

cai connect stores everything the CLI needs. Two settings are worth knowing:

• CAI_TOKEN — pass a credential through the environment instead of the config file. Useful in CI, scripts, and sandboxes.
• CAI_CONFIG — use an alternate config file path, for example to keep a second account separate.

cai use <workflowId> pins your working workflow. Inside a project directory the pin is saved to .cai.json there, so parallel sessions in different directories never interfere.

Run cai doctor to verify Node.js, authentication, API access, installed skills, and credential-file permissions.