@salesforce/cap

Coding Agent Platform (CAP) CLI: a non-interactive command-line tool for managing agents, projects, configuration, and local MCP definitions.

Prerequisites

• Node.js >=22.22.1
• npm 10+

Install

npm install --global @salesforce/cap
cap discover --output-format json
cap agent create --schema --output-format json

Start with discover for a cheap index: it lists every command with its summary and nothing else, so an agent can pick a command before paying for a full contract. Narrow it with --search <terms>, which keeps commands whose name or summary contains every space-separated term (case-insensitive). The usual flow is discover to choose, then <command> --schema for that command's full contract.

Command Output Schemas

<command> --schema --output-format json prints that one command's contract as JSON and exits before the command runs, the same lifecycle position as --help. Every command accepts --schema; the descriptor inlines the command's name, summary, params, error descriptors, safety data, and final-result JSON Schema. A streaming command such as project:files:watch returns no final result, since it only emits events, so its schema describes an empty output. cap --schema with no command returns MISSING_INPUT at exit 2.

Commands

Run an installed command as cap <command>. The current public commands are:

• Agents: agent:create, agent:list, agent:display, agent:update, agent:delete
• Agent conversation: agent:chat:send, agent:chat:events, agent:chat:history, agent:chat:agui, agent:chat:resolve, agent:chat:compact, agent:chat:context, agent:chat:create, agent:chat:list, agent:chat:display, agent:chat:delete, agent:mcp:reconnect
• Projects: project:create, project:list, project:display, project:rename, project:delete, project:deploy, project:templates:list
• Project files: project:files:read, project:files:write, project:files:tree, project:files:watch
• Models: model:list
• Skills: skill:init, skill:list, skill:upload, skill:merge, skill:delete, skill:files:delete
• Orgs: org:add
• Workspaces: workspace:list, workspace:display, workspace:create, workspace:start, workspace:stop, workspace:restart, workspace:delete
• Local backend: start
• Setup: setup:skill
• Configuration: config:get, config:set
• MCP definitions: mcp:add, mcp:list, mcp:display, mcp:delete
• Environment: doctor
• Metadata: discover, version (plus the universal --schema interrupt flag on every command)

All commands default to --output-format text. Use --output-format json for one machine-readable result, or --output-format stream-json when a streaming command emits NDJSON progress events before its final result.

Backend Targeting

Commands that access backend data target http://127.0.0.1:57342 by default. Use --workspace local explicitly or change the port with --backend-port:

cap project:list --workspace local
cap project:list --backend-port 5555 --output-format json

A non-local --workspace <id> (id, exact name, or unique name prefix) is resolved through the Workspace Manager: the CLI authenticates the selected org, then proxies backend calls to the workspace with its proxy token. Point at a self-hosted or staging manager with --workspace-url; --backend-url (a test/debug override) and the secret-bearing --proxy-token stay hidden. Persist a non-default endpoint once with config:set backendUrl <url> or config:set workspaceUrl <url> rather than repeating the flag, and source --proxy-token from the environment.

Serving the Web Experience

cap start serves the bundled web experience over localhost against a local or remote workspace, opens a browser, and stays attached until interrupted. The local mode boots Docker and seeds org credentials; the remote mode resolves the workspace through the Workspace Manager. The npm package includes the production web bundle.

cap start -w local -o my-org
cap start -w my-workspace -o my-org
cap start -w local -o my-org --port 3002 --docker-port 57343

Use --output-format stream-json for startup progress. --port selects the UI port (the next free port from 3001 by default), and --docker-port selects the local backend port (57342 by default). --workspace-url points at a custom Workspace Manager; --backend-url and --proxy-token remain hidden test/debug flags.

The packaged command serves the built web bundle. For Vite source development in the monorepo, start the backend with cap start -w local -o my-org, then run npm run dev --workspace ./packages/web.

Local MCP Definitions

MCP commands save server definitions locally in ~/.sf/cap.json; they do not start or probe a server. Provide a JSON definition with mcp:add, then attach its saved name when creating or updating an agent:

cap mcp:add --name local-tools --file ./mcp.json
cap agent:create --mcp local-tools

mcp:list and mcp:display redact argument values, environment values, headers, and URL credentials or query values.

Talking to an Agent

The conversation commands manage chat sessions on an agent and exchange messages with it. They emit json and stream-json only; there is no interactive terminal experience.

cap agent:chat:create --agent <id> --output-format json
cap agent:chat:send --agent <id> --chat <chat> --message "hello" --output-format json
cap agent:chat:send --agent <id> --chat <chat> --message "hello" --wait --output-format stream-json
cap agent:chat:events --agent <id> --chat <chat> --output-format stream-json

agent:chat:create seeds the chat from the project's initial messages unless --no-seed is passed. agent:chat:send and agent:chat:resolve default to the native transport and accept --transport ag-ui for an AG-UI run. Message history is split by transport because the two responses have different shapes: agent:chat:history returns the native history and agent:chat:agui returns the AG-UI snapshot. agent:chat:send --wait and agent:chat:events stream the backend's raw SSE event payloads as NDJSON; agent:chat:resolve submits a tool decision or result for a pending interaction. agent:chat:compact summarizes a chat into a new session, agent:chat:context reports context-window usage, and agent:mcp:reconnect reconnects one MCP server on a running agent.

Registering an Org

org:add registers a Salesforce org with the backend auth-service. Pass -o <alias> to resolve the credentials from the local sf auth store, or pass --alias, --access-token, and --instance-url together to register raw credentials. Add --set-default to register the org as the backend default.

cap org:add -o my-org --set-default
cap org:add --alias my-org --access-token <token> --instance-url https://example.my.salesforce.com

Environment Check

doctor reports whether the local environment is ready: Docker daemon running, the workspace container image present, and a configured email in ~/.sf/cap.json. It reports status and never fails on an unready environment, so a caller reads the ready flag and per-check results rather than the exit code.

cap doctor --output-format json

License

See LICENSE.txt.