Skip to main content

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.

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

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:
FlagDescription
--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
--useImmediately switch to this profile after saving
--clear-app-urlRemove the stored app URL
--clear-tokenRemove the stored token
--clear-agent-idRemove the stored agent ID
--clear-domain-idRemove the stored domain ID
--api-url is intentionally unsupported. Set --app-url and let oi derive the backend endpoint automatically.
Example — configure the default profile: 
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
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:
VariableOverrides
OPENINDEX_TOKENProfile token
OPENINDEX_AGENT_IDProfile agent_id
OPENINDEX_DOMAIN_IDProfile domain_id