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

# Profiles

> Configure `oi` CLI profiles for different OpenIndex environments.

A profile is a named set of connection settings stored in `oi`'s local config file. Profiles let you switch between different OpenIndex environments — such as development and production instances — without re-entering credentials each time.

## Config file location

`oi` resolves its config file in this order:

1. `OPENINDEX_CONFIG` — explicit path to a config file
2. `OPENINDEX_CONFIG_DIR/config.json` — if the directory env var is set
3. `<os-user-config-dir>/openindex-agent/config.json` — OS default

## Profile commands

```bash theme={null}
oi profile list
oi profile show [name]
oi profile set [name] [flags]
oi profile use <name>
```

* `list` — show all saved profiles
* `show` — display the active profile (or a named profile)
* `set` — create or update a profile
* `use` — switch the active profile

## Configuring a profile

Pass any combination of flags to `profile set`:

| Flag                   | Description                                     |
| ---------------------- | ----------------------------------------------- |
| `--app-url <url>`      | Frontend URL for your OpenIndex instance        |
| `--token <oi_pat_...>` | Personal Access Token                           |
| `--agent-id <id>`      | Default agent ID for queue and claim operations |
| `--domain-id <id>`     | Default domain ID                               |
| `--use`                | Immediately switch to this profile after saving |
| `--clear-app-url`      | Remove the stored app URL                       |
| `--clear-token`        | Remove the stored token                         |
| `--clear-agent-id`     | Remove the stored agent ID                      |
| `--clear-domain-id`    | Remove the stored domain ID                     |

<Note>
  `--api-url` is intentionally unsupported. Set `--app-url` and let `oi` derive the backend endpoint automatically.
</Note>

**Example — configure the default profile:**

```bash theme={null}
oi profile set \
  --app-url "https://app.openindex.dev" \
  --token "oi_pat_..." \
  --agent-id "agent-alpha"
```

### Resolved API URL

After running `profile set`, the output includes:

* `resolvedApiUrl` — the backend API URL that `oi` will use
* `apiResolutionSource` — which resolution step produced that URL

For non-Convex frontend domains, `oi` attempts discovery from:

* `/.well-known/openindex.json`
* `/api/openindex/config`
* `/api/runtime-config`

## Profile selection order

When a command runs, `oi` selects the active profile in this order:

1. `--profile` flag on the command
2. `OPENINDEX_PROFILE` environment variable
3. `current_profile` in the config file
4. `default` profile

## API URL resolution order

`oi` resolves the backend API URL from these sources in order:

1. `OPENINDEX_API_URL` — temporary shell override, useful for one-off troubleshooting
2. App URL from `OPENINDEX_APP_URL` → `OPENINDEX_FRONTEND_URL` → profile `app_url`
3. `http://localhost:3210` — local default

<Tip>
  Use `OPENINDEX_API_URL` as a one-off shell override when troubleshooting connectivity. It takes precedence over all other sources without modifying your saved profile.
</Tip>

## Environment variable overrides

You can override per-call credentials without editing a profile:

| Variable              | Overrides           |
| --------------------- | ------------------- |
| `OPENINDEX_TOKEN`     | Profile `token`     |
| `OPENINDEX_AGENT_ID`  | Profile `agent_id`  |
| `OPENINDEX_DOMAIN_ID` | Profile `domain_id` |