Skip to main content
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

  • 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:
--api-url is intentionally unsupported. Set --app-url and let oi derive the backend endpoint automatically.
Example — configure the default profile:

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