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.
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:
3

Configure a profile

Profiles store your connection settings locally. Configure your default profile with your instance URL, token, and an agent identifier:
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:
4

Verify your connection

Run the connectivity and auth checks to confirm everything is working:
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:
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:
To get the agent-oriented context bundle — current goal, allowed exits, blocked exits, and required fields — use:

​
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:
Command failures in JSON mode emit a structured error on stderr:
To inspect the machine-readable schema for all commands and their parameters:

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