CLI overview

The protobox CLI is built around the jobs you actually do with a workspace: prove your key works, hook the MCP server into a client, look at and run tools, connect an app, and handle the occasional bit of housekeeping — toolsets, secrets, approvals.

Install

npm install -g @protoboxai/cli

Verify:

protobox --version

2.1.0

@protoboxai/cli 2.0 is a breaking redesign of the command tree and the auth model. If you're upgrading from 1.x, see What changed in 2.0 below before scripting against it.

Authenticate

There's no browser login — the CLI takes a workspace API key and verifies it with a live call. Interactively, protobox login prompts Paste your workspace API key: (masked); non-interactive (CI, coding agents) it takes the key as a flag and never prompts:

protobox login --api-key YOUR_API_KEY --base-url https://platform.protobox.ai

✓ Key verified — Orders (https://acme.protobox.app/mcp/srv/orders)
ℹ Next: protobox status

Get a key from app.protobox.ai → Settings → API keys. See Configuration for profiles, --base-url, and environment variable overrides.

Check what you're connected to

protobox status

Profile: default
Platform: https://platform.protobox.ai
API key: ak_6********FtBV
MCP · Orders: https://acme.protobox.app/mcp/srv/orders
Connections: none — connect one: protobox connect <app>
Toolsets: 20

whoami is the same command under a second name — use whichever reads better in a script.

Command map

Commands

Session

Command	Does
`protobox login [--api-key K] [--base-url U] [--profile P]`	Store and verify a workspace API key
`protobox logout [--profile P]`	Remove the stored key
`protobox status` (alias `whoami`)	Workspace, MCP URL, key fingerprint, connection + toolset counts
`protobox config list / use / set-url / path`	Manage profiles and platform URL

MCP server

Command	Does
`protobox mcp url`	Print the MCP server URL — pasteable, nothing else
`protobox mcp connect <claude\|cursor\|vscode\|windsurf\|raw>`	Emit and offer to install a client's config block
`protobox mcp test`	Live handshake: initialize → tools/list
`protobox mcp keys list / create / revoke <id>`	MCP server key lifecycle

Tools

Command	Does
`protobox tools [--app A] [--search Q]`	List tools — friendly name, mono slug, one-line description
`protobox tools get <name>`	Schema, required args, which connection it needs
`protobox tools run <name> [-a k=v…\|--args JSON] [--user U]`	Execute a tool and print the result verdict
`protobox tools logs [--tool N] [-n 20]`	Recent executions with verdicts
`protobox tools add-api --spec <openapi.json>`	Register your own API as tools
`protobox tools add-code --file <fn.js>`	Register a code connector
`protobox tools remove <slug>`	Unregister a custom connector

Apps and connections

Command	Does
`protobox apps [--search Q]`	The app catalog, with connection state
`protobox apps actions <app>`	The tools an app exposes
`protobox connect <app> [--user U] [--api-key K] [--no-browser]`	Start an OAuth or API-key connection
`protobox connections [--user U]`	Status per connection
`protobox connections remove <id>`	Revoke and delete a connection's credential

Knowledge and skills

Command	Does
`protobox kb [--search Q]`	List entries; `--search` runs retrieval, not name matching
`protobox kb add <file\|url\|"text">`	Ingest content
`protobox kb get <id>` / `protobox kb remove <id>`	Inspect or delete an entry
`protobox skills` (alias `prompts`)	List skills — friendly name, category, description
`protobox skills get/create/edit/remove <name>`	Skill lifecycle, by name

Housekeeping

Command	Does
`protobox toolsets list / get / create / delete / add / remove`	Curate subsets of tools, by slug
`protobox secrets list / set / remove`	Values are prompted, never taken as an argument
`protobox approvals list / approve / deny <id>`	Pending tool-call approvals

See the Command reference for every flag.

Global options

Option	Description
`--json`	Output as JSON instead of a table
`--no-color`	Disable colored output
`-v, --version`	Print CLI version
`-h, --help`	Show help for any command

Output formats

Human output (default) — aligned columns, a slug under every friendly name:

protobox tools --search order

Name           Slug                       Description
────────────────────────────────────────────────────────────
Getorder       SHOPIFY_GETORDER           Get a single order.
Listorders     SHOPIFY_LISTORDERS         List orders (status=any|open|closed|cancelled).

--json for scripts — every read/run command supports it:

protobox tools --json | jq -r '.[].name'

Scripting

Exit code is 0 only when the underlying verdict succeeded — not just that the request reached the platform. tools run against a tool the workspace hasn't connected an app for exits non-zero even though the transport call returned 200:

protobox tools run SHOPIFY_GETORDER -a order_id=1 || echo "tool call did not succeed"

✗ Error: SHOPIFY_GETORDER → failed
   Connect first: 'protobox connect shopify'
tool call did not succeed

CI/CD

- name: Verify the workspace connection
  run: protobox status --json
  env:
    PROTOBOX_API_KEY: ${{ secrets.PROTOBOX_API_KEY }}

What changed in 2.0

2.0 redesigns the command tree around jobs instead of nouns, and drops browser login for a verified API key. If you scripted against 1.x, these are the breaking changes:

1.x	2.0	Why
`protobox login` (browser) / `protobox auth status`	`protobox login --api-key` / `protobox status`	No working browser flow in 1.x; a verified key is simpler and CI-friendly
`protobox workspaces list/get/use`	gone — `protobox status` + `protobox config use <profile>`	A profile already pins one workspace; a second selector was redundant
`protobox health`	folded into `protobox status` and `protobox mcp test`	A bare ping with no auth context answered nothing
`protobox mcp tools/call/inspect <agent-id>`	`protobox tools run <name>` / `protobox mcp test`	`agent-id` was leftover from a different product; tools are addressed by name everywhere now
`protobox knowledge …`	`protobox kb …`	Shorter, matches the dashboard
`protobox prompts …`	`protobox skills …` (alias `prompts`)	Matches the skills-library naming elsewhere in the product
`protobox tools categories`, `enable/disable`	gone — use `protobox toolsets` to curate	Toolsets are the curation surface in 2.0

What's next

MCP integration

Connect Claude, Cursor, VS Code, and Windsurf

Command reference

Every command and flag

Configuration

Profiles, config file, and environment variables

Error reference

What each error means and the command it tells you to run

Search

MCP integration

Command reference

Configuration

Error reference

On this page