> ## Documentation Index
> Fetch the complete documentation index at: https://docs.galtea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

> Authenticate the Galtea CLI and explore the command surface

> [!WARNING]
>
> You are reading the docs of Galtea 5.12. [Read this page in the latest version](https://docs.galtea.ai/cli/usage.md).

The `galtea` CLI is a terminal-native client for the Galtea AI testing & evaluation platform. Every [REST API](https://docs.galtea.ai/v5.12/api-reference) operation ships as a `galtea <noun> <verb>` command, auto-generated from the live OpenAPI spec.

### What it can do

Anything the [Galtea API](https://docs.galtea.ai/v5.12/api-reference) 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.

> [tab] Interactive
>
> ```bash theme={"system"}
> 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](https://platform.galtea.ai/settings).

> [tab] Non-interactive / CI
>
> ```bash theme={"system"}
> export GALTEA_API_KEY=gsk_...
> ```
>
> > [!TIP]
> >
> > 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.

```bash theme={"system"}
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:

```bash theme={"system"}
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.

> [!NOTE]
>
> Run `galtea sync` after a new [Galtea API](https://docs.galtea.ai/v5.12/api-reference) release to refresh the command tree.

```bash theme={"system"}
galtea help
```

For parameter, request body, and response shape details, see the [**REST API**](https://docs.galtea.ai/v5.12/api-reference) tab.

### Hand it to your coding agent

The CLI is a great fit for AI coding assistants. Install the [Galtea Agent Skill](https://docs.galtea.ai/v5.12/sdk/integrations/agent-skill.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.