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

# Auth & Config

> Authenticate, manage profiles, and sync deployment secrets.

The xpander CLI authenticates per profile and stores credentials at `~/.xpander/credentials`. You can have multiple profiles for different organizations or environments (production, staging, …).

## `xpander login` (alias `l`)

Authenticate via browser. Opens xpander.ai in your default browser, completes the OAuth flow, and writes credentials to the active profile.

```bash theme={"dark"}
xpander login
xpander login --profile staging
xpander login --new           # force a new profile even if one exists
```

| Flag               | Description                                                                          |
| ------------------ | ------------------------------------------------------------------------------------ |
| `--profile <name>` | Profile name to write credentials to. Defaults to the active profile (or `default`). |
| `--new`            | Create a new profile even if one already exists with this name.                      |

## `xpander configure` (alias `c`)

Set up API credentials manually (for environments without a browser, or when you already have an API key).

```bash theme={"dark"}
xpander configure
xpander configure --key sk-... --org 8d185373-... --profile staging
xpander c --key sk-... --no-validate
```

| Flag                      | Description                                                                                                     |
| ------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `--key <api_key>`         | API key to store. If omitted, the wizard prompts.                                                               |
| `--org <organization_id>` | Organization ID. Optional: auto-detected from the key if omitted.                                               |
| `--profile <name>`        | Profile to write to.                                                                                            |
| `--no-validate`           | Skip credential validation against the cloud (useful when the API is unreachable but you know the key is good). |

The wizard:

1. Stores your API key in the profile.
2. Validates against xpander.ai (unless `--no-validate`).
3. Auto-detects your organization ID.
4. Writes both to `~/.xpander/credentials`.

Output:

```text theme={"dark"}
? Enter your Xpander API key: <your-key>
✔ API key validation successful
API key saved to profile "default".
Detecting organization ID...
✔ Organization ID detected: 8d185373-8b24-47a7-8607-3e9036b968bb
Credentials stored at: ~/.xpander/credentials
```

## `xpander profile`

Manage profiles.

```bash theme={"dark"}
xpander profile --list                    # list all profiles
xpander profile --set-default staging     # set the default profile
xpander profile --new                     # wizard for a new profile
xpander profile --new staging             # create profile named "staging"
xpander profile --edit staging            # edit an existing profile
xpander profile --verify                  # verify the current profile works
xpander profile --verify staging          # verify a specific profile
```

| Flag                   | Description                                                                       |
| ---------------------- | --------------------------------------------------------------------------------- |
| `--list`               | List all profiles.                                                                |
| `--set-default <name>` | Set a profile as the default.                                                     |
| `--new [name]`         | Create a new profile. Without a name, runs an interactive wizard.                 |
| `--edit <name>`        | Edit an existing profile.                                                         |
| `--verify [name]`      | Verify a profile by hitting the API. Without a name, verifies the active profile. |

Use `--profile <name>` on any command to override the active profile for a single call:

```bash theme={"dark"}
xpander agent list --profile staging
xpander agent deploy my-agent --profile production
```

## `xpander secrets-sync`

Upload your local `.env` variables to deployed agents as runtime secrets.

```bash theme={"dark"}
xpander secrets-sync
xpander secrets-sync --profile production
```

| Flag            | Description     |
| --------------- | --------------- |
| `--profile <n>` | Profile to use. |

This reads `.env` in the current directory and uploads each `KEY=value` line to the deployed agent's secret store. Existing secrets with the same key are overwritten.

Use this after `xpander agent deploy` whenever you change environment-dependent config without rebuilding the container: for example, rotating an external API key.

## Auth priority

When multiple credential sources are present, the CLI resolves auth in this order:

1. `--api-key` on the command line.
2. `XPANDER_API_KEY` environment variable.
3. `~/.xpander/credentials` (the active profile).

This lets CI runners override the local profile without touching it.

## Files and locations

| Path                     | Purpose                                                                                              |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| `~/.xpander/credentials` | Per-profile credentials (API key, organization ID).                                                  |
| `.env` (project root)    | Local env vars. Read by `xpander agent dev` and uploaded by `xpander agent deploy` / `secrets-sync`. |