Usage

Authenticate the Galtea CLI and explore the command surface

The galtea CLI is a terminal-native client for the Galtea AI testing & evaluation platform. Every REST API operation ships as a galtea <noun> <verb> command, auto-generated from the live OpenAPI spec.

What it can do

Anything the Galtea API does — every endpoint is reachable as a CLI command, with auth, retries, and shell completion handled for you.

Why use it

• Let your coding agent manage Galtea for you. Claude Code, Cursor, Windsurf, and other agents can use the CLI to create products, run evaluations, pull traces, and more — without leaving your editor.
• Script your workflows. Automate repetitive tasks like batch-creating tests, kicking off evaluations from CI/CD, or syncing specifications across environments.
• Faster than the dashboard for quick lookups. List the last 10 evaluations, check a session’s status, or pull traces in seconds.

Authentication

The CLI supports both an interactive flow for local use and a non-interactive flow for CI and Docker.

Interactive

galtea login
# Paste your gsk_* API key when prompted.

The key is validated against the server, then stored in your user config directory, typically ~/.config/galtea/apis.json, with mode 0600 (only your user can read it). You can grab a gsk_* key from the settings page.

Non-interactive / CI

export GALTEA_API_KEY=gsk_...

If GALTEA_API_KEY is exported in the environment, running galtea login becomes optional — running it anyway stores the key to disk for future shells.

Behind an API gateway

If your company puts an API gateway in front of Galtea, the gateway may ask for its own headers. Set them in GALTEA_EXTRA_HEADERS as a JSON object of header names to string values. The Python SDK uses the same variable and format.

export GALTEA_EXTRA_HEADERS='{"X-IBM-Client-Id":"<your-client-id>"}'
galtea login --host https://galtea-gateway.example.com

The CLI sends these headers on the galtea login key check and on every later command. It never writes them to apis.json. A profile that names its own auth handler in apis.json does not get them.

You can also save a header on the default profile in apis.json:

• The CLI sends a profile header only while that profile is active. With GALTEA_API_KEY set, the CLI uses another profile, so use GALTEA_EXTRA_HEADERS. Without it, galtea login fails at the key check.
• When you paste the key, galtea login sends the saved headers if they belong to the login host: the base in apis.json is that host, or you have not logged in yet.
• A login to another host does not send the saved headers. It removes them from apis.json and prints their names. To rotate the key, pass the same --host again.

Rules for both:

• When both set the same header, GALTEA_EXTRA_HEADERS wins.
• They cannot replace Authorization, User-Agent, Content-Type, Content-Length or Host. The CLI drops those with a warning.
• A value must be ASCII text with no leading or trailing space or tab.
• A redirect that changes the host, the scheme or the port drops these headers, as the Python SDK does. A subdomain is another host. A redirect from http to https on the default ports keeps them.

Your first command

Once you’re authenticated, list your products to validate end-to-end auth and connectivity:

galtea products list

If this returns a list (even an empty one) instead of a 401 Unauthorized, you’re ready to go.

Discovering all commands

These are the available OpenAPI commands that were downloaded to your machine.

Run galtea sync after a new Galtea API release to refresh the command tree.

galtea help

For parameter, request body, and response shape details, see the REST API tab.

Hand it to your coding agent

The CLI is a great fit for AI coding assistants. Install the Galtea Agent Skill and Claude Code, Cursor, Windsurf, or any other Agent-Skills-compatible client will reach for galtea on your behalf — picking the right command, handling authentication, and following the workflows our team has already validated, so you don’t have to brief your agent on Galtea first.