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.

This guide walks you through authenticating with OpenIndex and using the oi CLI to inspect your work queue and retrieve a work item.

​
Prerequisites

You need an active OpenIndex account with access to an OpenIndex instance before starting. If you don’t have one, contact your instance administrator.
1

Create a Personal Access Token

The oi CLI and the HTTP API authenticate using Personal Access Tokens (PATs).
  1. Sign in to the OpenIndex web UI.
  2. Navigate to Settings → Personal → Tokens.
  3. Click Create token, give it a name, and select the read_write scope.
  4. Copy the token value — it begins with oi_pat_ and is shown only once.
Store your token somewhere safe. You cannot view it again after leaving the creation screen.
2

Install the `oi` CLI

The install script detects your platform and installs the latest release of oi.
export GITHUB_TOKEN=<github-token-with-repo-read>
curl -fsSL -H "Authorization: Bearer ${GITHUB_TOKEN}" \
  https://raw.githubusercontent.com/CEOofSaturdays/OpenIndex/main/scripts/install-oi.sh | bash
GITHUB_TOKEN is required when releases are hosted in a private repository. To install a specific version, append -- --tag v0.10.0 to the command. To pin to stable releases only, append -- --stable.
To update an existing installation:
oi update
3

Configure a profile

Profiles store your connection settings locally. Configure your default profile with your instance URL, token, and an agent identifier:
oi profile set \
  --app-url "https://app.openindex.dev" \
  --token "oi_pat_..." \
  --agent-id "agent-alpha"
The CLI derives the backend API URL from --app-url automatically. The output includes resolvedApiUrl and apiResolutionSource so you can confirm the resolution path.If you prefer environment variables over a config file:
export OPENINDEX_TOKEN="oi_pat_..."
export OPENINDEX_AGENT_ID="agent-alpha"
4

Verify your connection

Run the connectivity and auth checks to confirm everything is working:
oi doctor
oi auth check
oi doctor validates your installation and reports configuration issues. oi auth check confirms your token is valid and shows your effective scope.
5

List your work queue

Pull the queue to see available and in-progress work:
oi queue list
The queue returns two buckets:
  • available — unresolved work items with executionTarget != human and no active agent assigned
  • mine — unresolved work items where activeAgentId matches your configured agent ID
6

Get a work item

Retrieve the full details for a specific work item by its key:
oi work-item get ABC-123
To get the agent-oriented context bundle — current goal, allowed exits, blocked exits, and required fields — use:
oi work-item agent-context ABC-123

​
Working in pipelines

When stdout is not a TTY — for example, in CI or when piping output — oi defaults to JSON output automatically. You can also force JSON mode explicitly with --json or -j: 
oi queue list --json | jq '.available[].key'
Command failures in JSON mode emit a structured error on stderr: 
{
  "error": {
    "code": "unauthorized",
    "message": "token is invalid or has been revoked",
    "hint": "Run `oi auth check` to diagnose",
    "next_command": "oi auth check"
  }
}
To inspect the machine-readable schema for all commands and their parameters: 
oi schema

​
Next steps

CLI Reference

Full reference for all oi commands: work items, queue, calendar, and settings.

API Reference

Explore the HTTP API for work items, workflows, and integrations.