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

# CLI Overview

> The `oi` agent CLI for OpenIndex — built for AI agents and operators.

`oi` is the agent-first CLI for OpenIndex. It is designed for machine use and scriptability, with all output modes tuned for both human operators and automated pipelines.

## Command groups

| Group       | Purpose                                                    |
| ----------- | ---------------------------------------------------------- |
| `queue`     | Pull available and active work                             |
| `work-item` | Read, create, update, and transition work                  |
| `calendar`  | View scheduled work and external calendar events           |
| `settings`  | Manage personal, domain, external, and admin configuration |
| `profile`   | Configure connection profiles                              |
| `auth`      | Verify authentication and token scope                      |

## Global flags

Every `oi` command accepts these flags:

| Flag               | Short | Description                   |
| ------------------ | ----- | ----------------------------- |
| `--profile <name>` |       | Select a named config profile |
| `--json`           | `-j`  | Force JSON output             |
| `--verbose`        | `-v`  | Include fuller error output   |

## JSON mode and auto-detection

When stdout is not a TTY (for example, in pipelines or scripts), `oi` defaults to JSON output automatically. In TTY mode, output is formatted for human-readable terminal usage.

When `--json` is active, command failures emit a structured error object on stderr:

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Token is invalid or expired.",
    "hint": "Run oi profile show to inspect the active token.",
    "next_command": "oi profile show"
  }
}
```

| Field                | Description                 |
| -------------------- | --------------------------- |
| `error.code`         | Machine-readable error code |
| `error.message`      | Human-readable description  |
| `error.hint`         | Suggested remediation       |
| `error.next_command` | Suggested follow-up command |

## Machine-readable schema

Run `oi schema` at any time to emit the full JSON Schema for all `oi` commands, arguments, and flags. Use this to drive structured invocations from an agent or build tooling on top of the CLI contract.

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

## Help topics

`oi` includes built-in narrative guides accessible without network access:

```bash theme={null}
oi help
oi help quickstart
oi help auth
oi help profile
oi help domain
oi help calendar
oi help work-item
oi help workflow
oi help scheduling
oi help updates
oi help troubleshooting
oi help all
```

For command groups not covered by `oi help` topics (such as `settings`), use `--help`:

```bash theme={null}
oi settings --help
oi settings personal --help
oi settings domain --help
oi settings external --help
oi settings admin --help
```

## Auth diagnostics

```bash theme={null}
oi auth check
oi whoami
```

Use `oi auth check` to verify that your token is valid and inspect its effective scope. Use `oi whoami` to confirm the authenticated identity.

## Explore the CLI

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/cli/installation">
    Install `oi` from GitHub releases, Homebrew, or source.
  </Card>

  <Card title="Profiles" icon="user" href="/cli/profiles">
    Configure profiles for different OpenIndex environments.
  </Card>

  <Card title="Work Items" icon="list-check" href="/cli/work-items">
    Create, update, claim, and complete work items.
  </Card>

  <Card title="Queue" icon="inbox" href="/cli/queue">
    Inspect available and active work.
  </Card>

  <Card title="Calendar" icon="calendar" href="/cli/calendar">
    View calendar events and manage ICS sources.
  </Card>

  <Card title="Settings" icon="gear" href="/cli/settings">
    Manage personal, domain, external, and admin settings.
  </Card>
</CardGroup>