Authentication

Getting an API Key

Get your API key from platform.pretorin.com. For a customer-managed deployment, get it from that deployment’s /api/tokens page and use its public API URL with --api-url.

Beta Note: Framework and control browsing works for authenticated users. Platform write features (evidence, narratives, monitoring) require a beta code. Systems can only be created on the platform, not through the CLI or MCP. Sign up for early access.

All hosted API access is account-scoped and authenticated. Access to Pretorin-hosted services and any returned account-scoped data is governed by the applicable platform terms in addition to the open-source license for this repository.

Login

pretorin login

Options:

You’ll be prompted to enter your API key. Credentials are stored in ~/.pretorin/config.json.

If you’re already authenticated to the same API URL, pretorin login validates the existing key and skips the prompt. A different --api-url asks for a new key. To re-authenticate with a different key, include the intended API URL:

pretorin login --api-key <new-key> --api-url <platform-api-url>

If you log into a different API endpoint or switch API keys, Pretorin clears the stored active system + framework context so stale scope does not bleed into the new environment.

Verify Authentication

$ pretorin whoami
╭──────────────────────────────── Your Session ────────────────────────────────╮
│ Status: Authenticated                                                        │
│ API Key: pretorin...9v7o                                                     │
│ API URL: https://platform.pretorin.com/api/v1/public                         │
│ Frameworks Available: 26                                                     │
╰──────────────────────────────────────────────────────────────────────────────╯

For machine-readable output, use the global --json flag:

pretorin --json whoami

Logout

Clear stored credentials:

pretorin logout

If PRETORIN_API_KEY or a platform URL environment variable is set, logout warns that the environment session remains active. Unset those variables to end it.

Environment Variables

You can supply credentials via environment variables instead of pretorin login. Environment variables take precedence over stored config:

export PRETORIN_API_KEY=pretorin_your_key_here

# Optional — point at a self-hosted or local platform instead of the default.
export PRETORIN_PLATFORM_API_BASE_URL=https://platform.example.com/api/v1/public

# Optional — use a separate model provider endpoint. Without this, the CLI
# derives the matching model proxy from the platform URL above.
export PRETORIN_MODEL_API_BASE_URL=https://platform.example.com/api/v1/public/model

This is useful for CI/CD pipelines and containerized environments.

Set the key and the URL together. An API key is bound to the platform URL it was issued against, so Pretorin never joins a stored key with an independently overridden URL. If you are already logged in and export only PRETORIN_PLATFORM_API_BASE_URL (or the legacy PRETORIN_API_BASE_URL) with a value that differs from your saved platform_api_base_url, the CLI fails closed and reports Not logged in yet — it does not silently send your production key to the new endpoint. Export PRETORIN_API_KEY alongside it, or run pretorin login --api-key <key> --api-url <url> to switch deployments.

When an environment platform URL differs from the saved platform URL, the CLI derives its model proxy from the environment platform. A saved model URL for the other deployment is ignored. Set PRETORIN_MODEL_API_BASE_URL only when you intentionally use a separate model provider endpoint.

PRETORIN_API_BASE_URL is accepted as a legacy alias for PRETORIN_PLATFORM_API_BASE_URL; when both are set, the platform-prefixed name wins. See Environment Variables for the full list.