Configuration & Secrets

The Protobox CLI stores configuration in a local file and supports environment variable overrides. This page covers authentication, config management, tool secrets, and multi-environment workflows.

Config File

CLI configuration lives in ~/.protobox/config.json. The CLI creates it automatically on first use.

protobox config path

/Users/you/.protobox/config.json

What's stored

The config file holds your credentials, workspace context, and display preferences. Sensitive values (API key, tokens) are stored in plaintext — protect the file with standard filesystem permissions.

{
  "apiKey": "YOUR_API_KEY",
  "baseUrl": "https://platform.protobox.ai",
  "workspaceId": "ws_abc123",
  "defaultFormat": "table"
}

Reset config

rm ~/.protobox/config.json

The CLI recreates it with defaults on the next command.

Authentication

The CLI supports two methods: browser login and API key.

protobox login

Opening browser for authentication...
If the browser didn't open, visit:
  https://app.protobox.ai/cli-auth?port=54321

✓ Authentication successful

User:       dean@acme.com
Workspace:  ws_abc123

✓ Credentials saved to /Users/you/.protobox/config.json

protobox login --api-key YOUR_API_KEY

Check auth status

protobox auth status

Log out

protobox logout

Logout removes all stored credentials (API key, JWT, refresh token) and clears the workspace ID.

API Keys

API keys are created in the Protobox dashboard, not from the CLI.

protobox login --api-key YOUR_API_KEY

To rotate a key, create a new one, update your CLI config or CI secrets, then revoke the old key.

Config Commands

List all config

protobox config list

The Source column shows where each value comes from:

Get / set / delete

protobox config get baseUrl
protobox config set defaultFormat json
protobox config delete workspaceId

config delete and config unset are aliases.

Switch environment

protobox config use production

For a custom endpoint, set the base URL directly:

protobox config set baseUrl https://platform.protobox.ai

Config Keys

Environment Variables

Environment variables override config file values — the recommended approach for CI/CD and containers.

Priority order

Environment variable > Config file > Built-in default

CI/CD example

steps:
  - name: List workspace tools
    run: protobox tools list --json
    env:
      PROTOBOX_API_KEY: ${{ secrets.PROTOBOX_API_KEY }}
      PROTOBOX_WORKSPACE_ID: ${{ vars.PROTOBOX_WORKSPACE_ID }}

Shell profile example

export PROTOBOX_API_KEY=YOUR_API_KEY
export PROTOBOX_WORKSPACE_ID=ws_abc123

Tool Secrets

Tools can reference secrets with the {{secret:name}} syntax in their configuration. Secrets are managed through the dashboard — the CLI does not create or modify them.

How secrets work

{
  "name": "weather_api",
  "type": "http",
  "configuration": {
    "http": {
      "url": "https://api.weather.com/v1/forecast",
      "headers": { "Authorization": "Bearer {{secret:WEATHER_API_KEY}}" }
    }
  }
}

At runtime, the platform resolves {{secret:WEATHER_API_KEY}} to the value stored in the workspace's secret store. The value never appears in logs, API responses, or tool definitions.

Managing secrets

Inspect a secret reference from the CLI

You can see which tools reference secrets, but not the resolved values:

protobox tools get <tool-id> --json | jq '.configuration.http.headers'

{ "Authorization": "Bearer {{secret:WEATHER_API_KEY}}" }

SDK Configuration

When using @protoboxai/sdk directly, pass configuration to the constructor:

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

const client = new ProtoboxSDK({
  baseUrl: 'https://platform.protobox.ai',
  apiKey: process.env.PROTOBOX_API_KEY,
  timeout: 30000,
  retry: { maxRetries: 3, retryDelay: 1000, backoffMultiplier: 2 },
});

Troubleshooting

Related