Skip to main content
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 OpenAPI spec of the Galtea API release it was built with.

​
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.
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.

​
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.
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. The --host URL can include the path the gateway publishes Galtea under, such as https://galtea-gateway.example.com/my-org/galtea. 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:
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 commands your CLI version ships with.
For parameter, request body, and response shape details, see the REST API tab.

​
Getting new commands

The CLI does not download its commands from the API. Each CLI version has the commands of the Galtea API release it was built with. So one CLI version always offers the same commands, and a script that works today keeps working until you upgrade. When the API adds an operation, the operation reaches the CLI in the next CLI release. If a command from the REST API is missing in your CLI, update the CLI with the tool you installed it with.
galtea sync is deprecated. It does nothing, prints how to update the CLI, and will be removed on 2028-01-17. Remove it from your scripts.

​
Deprecation warnings

When you use a command, flag, or request body field that Galtea plans to remove, the CLI prints one line on stderr. The command still runs, and stdout holds only the response, so galtea ... -o json > out.json keeps working. Every warning has the same shape: what goes, when, and what to do next. These examples use made-up commands:
  • “Use … instead”: change your script to the replacement before the date.
  • “It has no replacement”: the feature is retired. Remove the call or the option before the date.
  • “Update the CLI”: the API deprecated this after your CLI version was released. Update the CLI, then run the command with --help to see its replacement.
A deprecated command or flag no longer shows in --help, but it keeps working until its removal date. A command that was renamed keeps working under its old name until that date, and the warning names the new one.

​
Version checks

The CLI asks the Galtea platform if it serves your CLI version. It asks at galtea login, and before a command at most once a day. It also asks again right after you update the CLI.
  • The platform cannot serve your CLI version. This happens when the CLI is newer than the platform, or when the platform no longer supports its major version. The command stops with exit code 10 before it sends its request. The message names the command of each install tool (Homebrew, APT, DNF and pip) that installs a matching CLI, and links to Install an older version.
  • Your CLI version has an end date. A warning names the date and the update command of each install method. The command runs.
  • A newer CLI is available. A notice names the new version and the update commands. The command runs.
The warning and the notice print only on the run that asks, so you see them at most once a day. If the platform cannot answer, the command runs. If galtea login finds a CLI version the platform cannot serve, it does not save the key and exits with code 10. Install a matching CLI, then log in again. The commands that report on the platform itself, such as galtea health, galtea build-info and galtea platform-compatibility, skip the check, so they still run on a blocked CLI.

​
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.