Authentication

The CLI authenticates using a personal access token (PAT). Tokens begin with the sapi_ prefix and are created through the web session or via the CLI once you have an existing token.

Create a token

Use sureva auth token create to generate a new PAT. You must supply an expiry date in RFC 3339 format. The --name flag is optional and defaults to cli-token if omitted.

sureva auth token create --name my-token --expires-at 2026-12-31T00:00:00Z

The raw token value is returned once in the JSON response and cannot be retrieved again. Copy it immediately.

{
  "id": "tok_...",
  "name": "my-token",
  "token": "sapi_abc123...",
  "expires_at": "2026-12-31T00:00:00Z"
}

auth login — not implemented

sureva auth login is not yet implemented. The command always returns a not_implemented error. Device-flow authentication is planned for a future release. Until then, create tokens via auth token create (requires an existing token) or through the Sureva web app, then export them as SUREVA_TOKEN.

Credential resolution order

The CLI resolves credentials in this order (first match wins):

Priority	Source
1	SUREVA_TOKEN environment variable
2	token field in the config file

Environment variable (recommended for CI and agents)

Set SUREVA_TOKEN in your shell or CI environment:

export SUREVA_TOKEN=sapi_abc123...

In GitHub Actions or similar CI systems, store the token as a secret and inject it as an environment variable.

env:
  SUREVA_TOKEN: ${{ secrets.SUREVA_TOKEN }}

Config file

The CLI reads configuration from:

Platform	Path
Linux / macOS	~/.config/sureva/config.yaml
Windows	%APPDATA%\sureva\config.yaml

File permissions must be 0600 (owner read/write only). The CLI refuses to read config files with broader permissions.

Example config file:

token: sapi_abc123...
org: my-org
api_url: https://api.sureva.com

API URL resolution

Priority	Source
1	SUREVA_API_URL environment variable
2	api_url field in the config file
3	Default: https://api.sureva.com

Org resolution

Many commands require --org. The CLI resolves the organization in this order:

Priority	Source
1	--org <slug> flag
2	SUREVA_ORG environment variable
3	org field in the config file

Verify authentication

sureva auth whoami

Manage tokens

Command	Description
sureva auth token list	List all your PATs (raw value never shown)
sureva auth token revoke <id>	Revoke a token by its ID