Configuration

The CLI stores one or more named profiles — each a platform URL plus a verified API key — in a local file, and lets environment variables override any of it. This page covers login, the config file, profiles, and CI-friendly non-interactive use.

Authenticate

There's no browser flow in 2.0. login takes a workspace API key and verifies it with a live call before storing anything — a bad key never gets saved as if it worked. Interactively it prompts Paste your workspace API key: (masked) when --api-key is omitted.

Get a key from app.protobox.ai → Settings → API keys.

Non-interactive

CI, scripts, and coding agents pass the key and base URL as flags — nothing 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

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

If a command would normally prompt (login without --api-key, connect without --no-browser) and stdin isn't a TTY, it fails with the flag to pass instead of hanging — this is what makes the CLI safe to run from CI and from coding agents.

Check status

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

Log out

protobox logout

✓ Logged out of profile 'default'

protobox status (or any authenticated command) after logout fails with the same instruction login gives on a rejected key:

✗ Error: Not logged in
   Run 'protobox login' (or set PROTOBOX_API_KEY)

Profiles

A profile is a name bound to one platform URL and one API key — switch between dev, staging, and prod without one credential silently overwriting another.

protobox login --api-key YOUR_KEY --profile staging
protobox config list

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

The * marks the active profile. Every command uses the active profile unless PROTOBOX_PROFILE is set.

Switch the active profile

protobox config use default

✓ Now using profile 'default'

Point a profile at a different platform URL

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

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

Where the config file lives

protobox config path

/Users/you/.protobox/config.json

{
  "currentProfile": "default",
  "profiles": {
    "default": {
      "apiKey": "ak_EXAMPLE_workspace.example_key_placeholder",
      "baseUrl": "https://platform.protobox.ai"
    },
    "staging": {
      "apiKey": "ak_EXAMPLE_workspace.example_key_placeholder",
      "baseUrl": "https://platform.protobox.ai"
    }
  }
}

The API key is stored in plaintext — protect the file with standard filesystem permissions.

Upgrading from 1.x

A 1.x config kept apiKey/baseUrl at the top level. The CLI migrates it into the default profile automatically the first time 2.0 runs — an upgrade never silently logs you out. The old top-level keys (jwtToken, refreshToken, server, deployment, apiPrefix, workspaceId, defaultFormat, appUrl) are dropped; none of them apply to the 2.0 auth model.

Environment variables

Environment variables always win over the config file — the recommended way to run the CLI in CI and containers, and from a coding agent that shouldn't touch your real ~/.protobox.

PROTOBOX_API_KEY=YOUR_KEY PROTOBOX_BASE_URL=https://platform.protobox.ai 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

Priority order

Environment variable > active profile > built-in default (https://platform.protobox.ai)

CI/CD example

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

Secrets

Tool configurations can reference a secret with {{secret:NAME}}; the platform resolves it at execution time and the value never appears in tool definitions, logs, or --json output. The CLI manages the values (never displaying them back), not the reference syntax inside a tool.

Interactively, protobox secrets set WEATHER_API_KEY prompts Value for WEATHER_API_KEY: and masks the input — the value never lands in shell history. --value exists for CI, where there's no TTY to prompt at:

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

secrets list prints keys, never values — there's no read-back command, by design.

protobox secrets remove WEATHER_API_KEY

✓ Removed WEATHER_API_KEY

Pass --user <id> to any secrets command to scope it to one end-user's credentials instead of the workspace's own.

SDK configuration

@protoboxai/sdk doesn't read ~/.protobox/config.json — that file is CLI-only. Pass configuration to the client constructor directly:

import { Protobox } from '@protoboxai/sdk';

const protobox = new Protobox({
  apiKey: process.env.PROTOBOX_API_KEY!,
  baseUrl: process.env.PROTOBOX_BASE_URL, // defaults to https://platform.protobox.ai
});

See the SDK reference for the full constructor and client surface.

Troubleshooting

Related