Command reference

Every protobox command accepts these flags:

Flag	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

This page documents the shipped 2.1.0 command tree. If you're coming from 1.x — workspaces, mcp tools/call/inspect <agent-id>, knowledge, and prompts as a standalone group are gone. See What changed in 2.0.

Store and verify a workspace API key.

protobox login [options]

Flag	Description
`--api-key <key>`	Workspace API key (prompted for when omitted)
`--base-url <url>`	Platform URL (default: `https://platform.protobox.ai`)
`--profile <name>`	Profile to store the key under

Interactively (no --api-key), it prompts Paste your workspace API key: and masks the input. Non-interactive:

protobox login --api-key ak_xxx --base-url https://platform.protobox.ai --profile staging

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

A rejected key fails loudly instead of storing itself:

✗ Error: Your API key was rejected
   Run 'protobox login' with a key from app.protobox.ai → Settings → API keys

logout

Remove the stored API key.

protobox logout [options]

Flag	Description
`--profile <name>`	Profile to log out of (default: current)

protobox logout

✓ Logged out of profile 'default'

status / whoami

Show workspace, MCP URL, key fingerprint, and connection/toolset counts. whoami is an alias for the same command.

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

protobox status --json

{
  "profile": "default",
  "baseUrl": "https://platform.protobox.ai",
  "servers": [
    { "slug": "orders", "name": "Orders", "url": "https://acme.protobox.app/mcp/srv/orders" }
  ],
  "connections": [],
  "toolsetCount": 20
}

config

Profiles and platform URL.

protobox config [command]

Subcommand	Description
`config list`	Show all profiles and which is active
`config use <profile>`	Switch the active profile
`config set-url [--profile P] <url>`	Point a profile at a different platform URL
`config path`	Print the config file location

protobox config list

   Profile  Platform                      Key
──────────────────────────────────────────────────────────
*  default  https://platform.protobox.ai  ak_6********FtBV
   staging  https://platform.protobox.ai  ak_6********FtBV

protobox config use default

✓ Now using profile 'default'

protobox config set-url https://platform.protobox.ai --profile staging

✓ Profile 'staging' now points at https://platform.protobox.ai

protobox config path

/Users/you/.protobox/config.json

mcp url

Print the MCP server URL — pasteable, nothing else.

protobox mcp url [options]

Flag	Description
`--server <slug>`	MCP server slug (required when a workspace has more than one)

protobox mcp url

https://acme.protobox.app/mcp/srv/orders

mcp connect

Emit — and offer to install — a client's config block: claude, cursor, vscode, windsurf, or raw.

protobox mcp connect <claude|cursor|vscode|windsurf|raw> [options]

Flag	Description
`--server <slug>`	MCP server slug (required when a workspace has more than one)
`--key <key>`	Reuse an existing server key instead of minting one
`-y, --yes`	Write the config file without confirming

protobox mcp connect claude

Client: Claude Desktop
MCP server: orders (https://acme.protobox.app/mcp/srv/orders)

{
  "mcpServers": {
    "orders": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://acme.protobox.app/mcp/srv/orders",
        "--header",
        "Authorization:Bearer pbk_xxxxxxxxxxxxxxxxxxxxxxx"
      ]
    }
  }
}

Config file: /Users/you/Library/Application Support/Claude/claude_desktop_config.json
ℹ Not written (non-interactive) — add it yourself, or rerun with --yes

With --yes, it writes the file (merging with any existing mcpServers) and backs up what was there:

protobox mcp connect claude --yes

✓ Added orders → /Users/you/Library/Application Support/Claude/claude_desktop_config.json
ℹ Previous config backed up to .../claude_desktop_config.json.bak
ℹ Next: restart Claude Desktop, then ask it "what tools do you have?"

See MCP integration for the per-client config shapes and the .bak/merge rules in full.

mcp test

Live Streamable-HTTP handshake: initialize → tools/list.

protobox mcp test [options]

Flag	Description
`--server <slug>`	MCP server slug (required when a workspace has more than one)
`--url <url>`	Override the MCP URL (e.g. a local runtime)
`--key <key>`	Server key to authenticate with (a temporary one is minted and revoked when omitted)

On success it reports Handshake ok — N tools in Xms. A rejected key fails with the same instruction mcp keys create gives:

✗ Error: MCP handshake failed
   The key was rejected — mint a new one: 'protobox mcp keys create'

mcp keys

Server key lifecycle.

protobox mcp keys [command] [options]

Flag	Description
`--server <slug>`	MCP server slug (required when a workspace has more than one)

Subcommand	Description
`keys list`	List a server's keys
`keys create [--name <label>]`	Mint a new server key
`keys revoke <id>`	Revoke a server key

protobox mcp keys create --name "ci-pipeline"

✓ Key created for 'orders'
Key: pbk_EXAMPLE_not_a_real_key
Prefix: pbk_DQfBwea7
! Warning: This is the only time the plaintext key is shown — store it now.
ℹ Next: protobox mcp connect claude --server orders --key pbk_EXAMPLE_not_a_real_key

protobox mcp keys list

ID                        Prefix        Last 4  Label         Status  Created
─────────────────────────────────────────────────────────────────────────────────────
6a7a95bff65a6055a0aa6527  pbk_DQfBwea7  KaUs    ci-pipeline   active  2026-08-11T03:23:43.407Z

protobox mcp keys revoke 6a7a95bff65a6055a0aa6527

✓ Revoked key '6a7a95bff65a6055a0aa6527'

tools

List, inspect, run, and manage tools.

protobox tools [options] [command]

Flag	Description
`--app <app>`	Filter by integration/app slug
`--search <query>`	Filter by name or description

Bare protobox tools lists — a list subcommand isn't needed:

protobox tools --search order

Name           Slug                       Description
────────────────────────────────────────────────────────────────
Cancelorder    SHOPIFY_CANCELORDER        ⚠️ DESTRUCTIVE — cancels an order …
Getorder       SHOPIFY_GETORDER           Get a single order.
Listorders     SHOPIFY_LISTORDERS         List orders (status=any|open|closed|cancelled).
…

ℹ Run one: protobox tools run <slug>

tools get

protobox tools get <name>

Tool: COINGECKO_SIMPLE_PRICE
Description: Get current prices for coins in given currencies.
Connection: coingecko

Arg                  Required  Type    Description
──────────────────────────────────────────────────
ids                  no        string
vs_currencies        no        string
include_market_cap   no        string
include_24hr_change  no        string

ℹ Run it: protobox tools run COINGECKO_SIMPLE_PRICE

tools run

Execute a tool and print the result verdict.

protobox tools run [options] <name>

Flag	Description
`-a, --arg <key=value>`	Argument as `key=value` (repeatable)
`--args <json>`	Arguments as a JSON object
`--user <id>`	End-user id whose credential to use

protobox tools run COINGECKO_SIMPLE_PRICE -a ids=bitcoin -a vs_currencies=usd

✓ COINGECKO_SIMPLE_PRICE → success in 183ms
  {
    "bitcoin": {
      "usd": 64040
    }
  }

protobox tools run COINGECKO_PING --json

{
  "name": "COINGECKO_PING",
  "success": true,
  "latencyMs": 65,
  "data": { "gecko_says": "(V3) To the Moon!" },
  "executionId": "6a7a9401b785d404478be4fd"
}

A tool whose app isn't connected fails with the connect instruction, and exits non-zero even though the platform request itself succeeded — see Errors:

✗ Error: SHOPIFY_GETORDER → failed
   Connect first: 'protobox connect shopify'

tools logs

protobox tools logs [options]

Flag	Description	Default
`--tool <id>`	Filter by tool id (see it in `--json` output)
`-n, --limit <count>`	Max rows to show	`20`

protobox tools logs -n 5

Verdict  Tool                    Latency  When
────────────────────────────────────────────────────────────────
success  COINGECKO_PING          65ms     Aug 10, 2026, 11:16 PM
success  COINGECKO_SIMPLE_PRICE  183ms    Aug 10, 2026, 11:16 PM
error    HTTPBIN_GETREQUEST      6ms      Aug 10, 2026, 11:03 PM

tools add-api

protobox tools add-api [options]

Flag	Description
`--spec <path>`	Path to an OpenAPI 3.x JSON file
`--slug <slug>`	Connector slug (default: derived from the spec file name)
`--name <name>`	Display name (default: the spec title)

protobox tools add-api --spec openapi.json --slug orders-api

✓ Registered 'orders-api' — Orders API
ℹ See its tools: protobox tools --app orders-api

tools add-code

protobox tools add-code [options]

Flag	Description
`--file <path>`	Path to the connector entry-point file
`--slug <slug>`	Connector slug (default: derived from the file name)
`--name <name>`	Display name (default: derived from the file name)
`--runtime <runtime>`	`node` or `python` (default: inferred from the file extension)

protobox tools add-code --file greet.js --slug greeter

✓ Registered 'greeter' — greet
ℹ See its tools: protobox tools --app greeter

tools remove

protobox tools remove <slug>

✓ Removed 'orders-api'

apps

The app catalog, with connection state.

protobox apps [options] [command]

Flag	Description
`--search <query>`	Filter by name or description

protobox apps --search cal

App              Slug            Auth    Connected
──────────────────────────────────────────────────
Cal.com          calcom          bearer  not connected
Calendly         calendly        bearer  not connected
Frankfurter      frankfurter     none    not connected
Google Calendar  googlecalendar  oauth2  not connected
Memory           memory          none    not connected

ℹ See an app's tools: protobox apps actions <app>

apps actions

protobox apps actions <app>

Tool                     Description
──────────────────────────────────────────────────
COINGECKO_PING           Check API server status.
COINGECKO_SIMPLE_PRICE   Get current prices for coins in given currencies.
COINGECKO_COINS_MARKETS  List coins with market data.
…

connect

Connect an app — OAuth opens a consent link; API-key apps take --api-key.

protobox connect [options] <app>

Flag	Description
`--user <id>`	End-user this connection is for (default: this CLI profile's name)
`--api-key <key>`	Credential for apps that authenticate with an API key (prompted for when omitted, interactive only)
`--no-browser`	Print the authorize URL instead of opening it

protobox connect brave-search --api-key YOUR_BRAVE_KEY

✓ Brave Search connected
ℹ Next: protobox apps actions brave-search

For an OAuth app, --no-browser prints Authorize: <url> instead of opening a browser tab, then polls until the connection turns active. An app the workspace has no managed OAuth credential for fails with the platform's validation instruction rather than a bare 400 — this is the real error every OAuth app in a fresh local workspace returns until an app credential is configured:

protobox connect asana --no-browser

✗ Error: The platform rejected the input
   No app credentials are configured for 'asana'. Configure a managed OAuth app for this
   integration, or pass appCredentialsId explicitly.

GitHub is a special case — it connects via a GitHub App install, which the CLI doesn't drive:

protobox connect github

✗ Error: GitHub can't be connected from here
   GitHub connects via a GitHub App install, which this CLI does not drive yet

connections

Status per connection.

protobox connections [options] [command]

Flag	Description
`--user <id>`	Show one end-user's connections instead of the workspace's own

protobox connections

App           Status  Scope      Expires
────────────────────────────────────────
brave-search  active  workspace  —

connections remove

protobox connections remove [options] <id>

Flag	Description
`--user <id>`	Remove one end-user's connection instead of the workspace's own

protobox connections remove brave-search

✓ Removed connection 'brave-search'
ℹ Next: protobox connections

toolsets

Curated subsets of tools.

protobox toolsets [command]

Subcommand	Description
`toolsets list`	List toolsets
`toolsets get <toolset>`	Show a toolset and its members
`toolsets create [--description T] [--tool S...] <name>`	Create a toolset
`toolsets delete <toolset>`	Delete a toolset
`toolsets add <toolset> <tools...>`	Add tools to a toolset
`toolsets remove <toolset> <tools...>`	Remove tools from a toolset
`toolsets override <toolset> <tool> [--name N] [--description T] [--clear]`	Rename/re-describe a tool as this toolset serves it (live)
`toolsets policy <toolset> [--require-approval T...] [--require-approval-all] [--clear-approvals]`	Show or set human-approval gates

protobox toolsets create support --description "For the support agent" --tool COINGECKO_PING

✓ Created toolset 'support'
ℹ Next: protobox toolsets add support <tool>

protobox toolsets get support

Name: support
Slug: support
Description: For the support agent

COINGECKO_PING

protobox toolsets add support COINGECKO_SIMPLE_PRICE

✓ Added COINGECKO_SIMPLE_PRICE to 'support'
ℹ Next: protobox toolsets get support

protobox toolsets remove support COINGECKO_SIMPLE_PRICE

✓ Removed COINGECKO_SIMPLE_PRICE from 'support'

Overrides rename a tool as this toolset serves it — the underlying tool is untouched, and the change applies to every client on every surface the toolset backs, immediately:

protobox toolsets override support COINGECKO_PING --name check_prices --description "Check crypto prices"

✓ 'COINGECKO_PING' now serves as 'check_prices' on every surface 'support' backs — live immediately

Policies gate tools behind human sign-off (approvals is the deciding half). With no flags, policy shows the current gates; --require-approval is repeatable and additive:

protobox toolsets policy support --require-approval check_prices

✓ check_prices now pause for human approval on 'support'
ℹ Decide from the queue: protobox approvals

protobox toolsets delete support

✓ Deleted toolset 'support'

secrets

Secret values for code / private connectors.

protobox secrets [command]

Subcommand	Description
`secrets list`	List secret keys at a scope (never values)
`secrets set [--user U] [--value V] <name>`	Set a secret value
`secrets remove [--user U] <name>`	Delete a secret

secrets set prompts for the value interactively (Value for <name>:, masked) — passing it as an argument leaks it into shell history. --value exists for CI only:

protobox secrets set WEATHER_API_KEY --value YOUR_KEY

✓ Set WEATHER_API_KEY
ℹ Next: protobox secrets list

protobox secrets list

WEATHER_API_KEY
CHANL_PLATFORM_API_KEY

protobox secrets remove WEATHER_API_KEY

✓ Removed WEATHER_API_KEY

approvals

Pending tool-call approvals.

protobox approvals [command]

Flag	Description
`--pending`	Only pending approvals (on `list`)

Subcommand	Description
`approvals list [--pending]`	List approvals
`approvals approve <id>`	Approve a pending tool call — replays it server-side
`approvals deny [--reason T] <id>`	Deny a pending tool call — terminal, no replay

protobox approvals list --pending

ℹ No pending approvals

protobox approvals list

ID                        Tool                                   Caller                    Status    Requested
──────────────────────────────────────────────────────────────────────────────────────────────────────────────
6a7a709cccf8fc3fd16d5add  UC_SDK_001_API_MSNXV1V2_CREATETICKET  uc_sdk_001_user_msnxv1v2  denied    2 hours ago
6a79393ffdc0fd4e5d72929c  guide                                  —                         approved  1 day ago

approve prints Approved <tool> for <caller>; deny prints Denied <tool> for <caller>, plus Reason: <text> when --reason was given.

kb

Knowledge base — what your MCP server can look up.

protobox kb [options] [command]

Flag	Description
`--search <query>`	Run retrieval (real search, not name matching)

Subcommand	Description
`kb add [--title T] [--no-wait] <file\|url\|"text">`	Ingest a file, a URL, or quoted text
`kb get <id>`	Inspect one entry
`kb remove <id>`	Delete an entry

protobox kb add "Return window is 30 days from delivery. Refunds process in 5-7 business days." --title "Returns policy"

✓ Added 'Returns policy'
ℹ Try it: protobox kb --search "Returns policy"

protobox kb

Title           Source  Status     Updated
───────────────────────────────────────────
Returns policy  manual  completed  Just now

ℹ Search it: protobox kb --search <query>

protobox kb --search "return policy"

Score  Title           Excerpt
───────────────────────────────────────────────────────────
0.02   Returns policy  Return window is 30 days from delivery…

protobox kb get 6a7a94bcf65a6055a0aa627e

Title: Returns policy
Source: manual
Status: completed

Return window is 30 days from delivery. Refunds process in 5-7 business days.

protobox kb remove 6a7a94bcf65a6055a0aa627e

✓ Removed 6a7a94bcf65a6055a0aa627e

skills (alias prompts)

Reusable prompts your MCP clients can pull.

protobox skills [command]

Subcommand	Description
`skills get <name>`	Show a skill
`skills create [--content T\|--file P] [--description D] <name>`	Create a skill (opens `$EDITOR` unless `--content`/`--file` given)
`skills edit [--content T\|--file P] [--description D] <name>`	Edit a skill in `$EDITOR`, or replace via `--content`/`--file`
`skills remove <name>`	Delete a skill

protobox prompts is the identical command under its alias — both work everywhere.

protobox skills

Name                                                Category    Description                                       Updated
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
zoom-out                                            general     When work has been heads-down on details long e…  22 hours ago
triage                                              general     When a batch of incoming issues or requests nee…  22 hours ago
using-protobox                                      onboarding  When the user asks what this MCP server or work…  22 hours ago

protobox skills create greeting --content "Say hello to the user by name." --description "Docs walkthrough skill"

✓ Created skill 'greeting'
ℹ See it: protobox skills get greeting

protobox skills get greeting

Name: greeting
Description: Docs walkthrough skill
Category: general

Say hello to the user by name.

protobox skills edit greeting --content "Say hello and mention the weather."

✓ Updated skill 'greeting'

protobox skills remove greeting

✓ Removed skill 'greeting'

Search

On this page