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

# Quick Start

> Get up and running with OpenIndex: create a token, install the CLI, and start working with your queue.

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.

<Steps>
  <Step title="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.

    <Warning>
      Store your token somewhere safe. You cannot view it again after leaving the creation screen.
    </Warning>
  </Step>

  <Step title="Install the `oi` CLI">
    The install script detects your platform and installs the latest release of `oi`.

    ```bash theme={null}
    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
    ```

    <Note>
      `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`.
    </Note>

    To update an existing installation:

    ```bash theme={null}
    oi update
    ```
  </Step>

  <Step title="Configure a profile">
    Profiles store your connection settings locally. Configure your default profile with your instance URL, token, and an agent identifier:

    ```bash theme={null}
    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:

    ```bash theme={null}
    export OPENINDEX_TOKEN="oi_pat_..."
    export OPENINDEX_AGENT_ID="agent-alpha"
    ```
  </Step>

  <Step title="Verify your connection">
    Run the connectivity and auth checks to confirm everything is working:

    ```bash theme={null}
    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.
  </Step>

  <Step title="List your work queue">
    Pull the queue to see available and in-progress work:

    ```bash theme={null}
    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
  </Step>

  <Step title="Get a work item">
    Retrieve the full details for a specific work item by its key:

    ```bash theme={null}
    oi work-item get ABC-123
    ```

    To get the agent-oriented context bundle — current goal, allowed exits, blocked exits, and required fields — use:

    ```bash theme={null}
    oi work-item agent-context ABC-123
    ```
  </Step>
</Steps>

## 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`:

```bash theme={null}
oi queue list --json | jq '.available[].key'
```

Command failures in JSON mode emit a structured error on `stderr`:

```json theme={null}
{
  "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:

```bash theme={null}
oi schema
```

## Next steps

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="terminal" href="/cli/overview">
    Full reference for all `oi` commands: work items, queue, calendar, and settings.
  </Card>

  <Card title="API Reference" icon="code" href="/api/overview">
    Explore the HTTP API for work items, workflows, and integrations.
  </Card>
</CardGroup>