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