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:
OPENINDEX_CONFIG — explicit path to a config fileOPENINDEX_CONFIG_DIR/config.json — if the directory env var is set<os-user-config-dir>/openindex-agent/config.json — OS default
Profile commands
oi profile list
oi profile show [name]
oi profile set [name] [flags]
oi profile use <name>
list — show all saved profilesshow — display the active profile (or a named profile)set — create or update a profileuse — 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 |
--api-url is intentionally unsupported. Set --app-url and let oi derive the backend endpoint automatically.
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 useapiResolutionSource — 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:
--profile flag on the commandOPENINDEX_PROFILE environment variablecurrent_profile in the config filedefault profile
API URL resolution order
oi resolves the backend API URL from these sources in order:
OPENINDEX_API_URL — temporary shell override, useful for one-off troubleshooting- App URL from
OPENINDEX_APP_URL → OPENINDEX_FRONTEND_URL → profile app_url
http://localhost:3210 — local default
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.
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 |