Softprobe CLI

Appearance

Authentication ​

Softprobe supports two primary deployment topologies: SaaS / Cloud and Self-Hosted / Enterprise. Authentication requirements are automatically negotiated by your client tools (such as the Go sp CLI and the spcode web app) depending on your target API URL.

Deployment Environments ​

EnvironmentAPI EndpointPrimary Auth HeaderRouting Header
SaaS / Cloudhttps://api.softprobe.aiAuthorization: Bearer <JWT>X-Tenant-ID: <tenant-id>
Self-Hosted / Enterprisehttp://<your-local-ip>:<port>access-token: <JWT>—

SaaS Edge Authentication (Cloud) ​

When interacting with the SaaS endpoint at https://api.softprobe.ai, the edge gateway enforces strict identity verification and tenant routing.

Every outbound request from your CLI, Java agent, or web applications must include both of the following HTTP headers:

http
Authorization: Bearer <SUPABASE_JWT_TOKEN>
X-Tenant-ID: <TENANT_ID>
  • Authorization: Bearer <token>: Your unique, cryptographically signed JSON Web Token (JWT) issued by the Softprobe identity provider.
  • X-Tenant-ID: <tenant-id>: The identifier of the specific tenant/organization namespace you are targeting.

TIP

Zero-Configuration Routing: When using our standard client tools (the Go sp CLI or the spcode IDE), these headers are injected automatically based on your active profile configuration. You do not need to manually append them.

Self-Hosted / Enterprise Authentication ​

For on-premises or private network deployments, security controls are typically managed at the perimeter. The self-hosted endpoint relies on a legacy header to assert user profiles:

http
access-token: <JWT>

NOTE

In highly secure enterprise intranets, this header can be pre-configured on agent hosts or bypassed entirely by the CLI.

Interactive CLI Login ​

For human developers working on their workstations, the standard interactive flow resolves credentials quickly and writes them to local storage.

1. Request Code ​

For self-hosted instances using email verification, request a one-time code:

http
GET /api/login/getVerificationCode/{userName}

2. Exchange Code for Token ​

Exchange the verification code for a valid access token:

bash
sp auth login --email developer@corp.com --code 123456

3. SaaS (Cloud) Interactive Prompt ​

If your active API endpoint points to https://api.softprobe.ai, the CLI will automatically prompt you to input your active Tenant ID:

text
Enter your Tenant ID: tenant-12345

Once entered, the CLI writes both the token and your Tenant ID to your local configuration profile in: ${XDG_CONFIG_HOME:-~/.config}/softprobe/config.jsonc

Non-Interactive Login (CI/CD & Agents) ​

For automated pipelines, non-interactive testing suites, or backend agent hosts, avoid interactive logins by configuring environment variables.

SaaS Cloud Environment Variables ​

Set the following environment variables in your runner or shell environment:

bash
export SP_TOKEN="eyJhbGciOiJIUzI1NiIsIn..."
export SP_TENANT_ID="tenant-12345"

Once defined, any CLI command will automatically inherit these credentials and inject the correct secure headers:

bash
sp app list --json

Enterprise/Local Environment Variables ​

For self-hosted instances, configure only the authorization token:

bash
export SP_TOKEN="eyJhbGciOiJIUzI1NiIsIn..."

Who Am I ​

To inspect your current authentication profile, active token, and resolved tenant context, use the whoami command:

bash
sp auth whoami --json

This decodes the local JWT payload and presents your username, expiration date, and configured tenant parameters.

Error Handling ​

When authentication or tenant authorization checks fail, the edge gateway or local endpoint returns the following standard responses:

SituationHTTP StatusCLI Exit CodeDescription
Missing Token401 Unauthorized3 (AUTH_REQUIRED)The request did not specify an active authorization token.
Invalid/Expired Token401 Unauthorized1 (API_ERROR)The signature verification failed or the token has expired.
Unauthorized Tenant403 Forbidden1 (API_ERROR)The authenticated user does not have permission to access the requested Tenant ID.