> ## Documentation Index
> Fetch the complete documentation index at: https://hireobi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Obi CLI overview

> Global options, output formats, exit codes, credential storage and environment variables of the obi CLI.

The `obi` CLI connects your machine to your Obi account and carries the Skill your assistant runs. In everyday use your assistant runs these commands for you; this reference is for when you want to run or script them yourself.

## Help and version

```bash theme={null}
obi --help
obi --version
obi capabilities --json
```

`--help` prints every command and its options. `capabilities` lists, as JSON, the commands and options this installed version supports.

## Global options

| Option | Meaning |
| - | - |
| `--json` | Print one JSON envelope instead of text; not with `--help` |
| `--timeout-ms <100-30000>` | Bound each request to the server, in milliseconds; 5000 by default. Only commands that call the server take it: `research`, `skill`, `capabilities` and a local `doctor` refuse it |

## JSON output

With `--json`, every invocation prints exactly one envelope:

```json theme={null}
{
  "schemaVersion": 1,
  "ok": true,
  "command": "status",
  "mode": "product",
  "data": {}
}
```

For example, `obi doctor --json` on a Mac with the video tools installed prints:

```json theme={null}
{
  "schemaVersion": 1,
  "ok": true,
  "command": "doctor",
  "mode": "local",
  "data": {
    "node": "v22.22.0",
    "cliVersion": "0.1.7",
    "origin": "https://agent.hireobi.com",
    "credentialStorage": "none",
    "videoTools": { "ytDlp": true, "ffmpeg": true },
    "diagnostic": "completed"
  }
}
```

`credentialStorage` is `keychain`, `secret-service` or `file` once this machine is signed in, and `none` before.

A failure has `"ok": false` and an `error` object instead of `data`:

```json theme={null}
{
  "schemaVersion": 1,
  "command": "status",
  "mode": "product",
  "ok": false,
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "This machine is not signed in to Obi.",
    "retryable": false,
    "nextAction": "Run obi login --expect-email <your professional email>."
  }
}
```

`mode` says where the result came from: `local` (this machine only), `product` (your account on Obi's servers) or `test` (a local synthetic server). `nextAction` is always the CLI's own sentence, never text relayed from a server.

After a timeout or a conflict on a write, read the current state before retrying.

## Exit codes

| Code | Meaning | Examples |
| - | - | - |
| 0 | Success | |
| 1 | Unexpected internal error | `INTERNAL_ERROR` |
| 2 | The command, its input or local storage was refused | `INVALID_USAGE`, `CONFIRMATION_REQUIRED`, `STORAGE_UNAVAILABLE` |
| 3 | Sign-in needed, pending or refused | `AUTH_REQUIRED`, `AUTHORIZATION_PENDING`, `ACCOUNT_MISMATCH` |
| 4 | The account or a feature is not ready | `EMAIL_NOT_VERIFIED`, `ACCOUNT_SETUP_REQUIRED`, `SKILL_INSTALL_FAILED` |
| 5 | The server refused the operation in the current state | `OWNER_REQUIRED`, `HARNESS_REQUIRED`, `HARNESS_WORK_CONFLICT`, `SCAN_BUDGET_NOT_AUTHORIZED` |
| 6 | The server could not be reached or answered with a refusal this CLI does not know | `NETWORK_UNAVAILABLE`, `REQUEST_TIMED_OUT`, `SERVICE_UNAVAILABLE`, `RATE_LIMITED` (retry later); `REQUEST_FAILED` (update the CLI) |
| 7 | The server answered in a form this CLI does not know; update the CLI | `INVALID_RESPONSE`, `DOMAIN_CHANGED` |

## Credentials and local state

The CLI keeps your connection in the system credential store: the macOS Keychain, or the freedesktop Secret Service through `secret-tool` on Linux. On Windows, and on any machine without one, sign in with `obi login --expect-email <email> --storage file` to keep it in an owner-only file instead. The CLI never prints tokens.

Local state lives in:

| System | Directory |
| - | - |
| macOS | `~/Library/Application Support/obi-cli` |
| Linux | `$XDG_STATE_HOME/obi-cli`, or `~/.local/state/obi-cli` |
| Windows | `%LOCALAPPDATA%\obi-cli` |

Version 0.1.8 moves the folder and the stored connection an earlier version kept under its former name, on its first run.

## Environment variables

| Variable | Effect |
| - | - |
| `OBI_LANGUAGE` | Language of the terminal welcome (`en` or `fr`); otherwise `LC_ALL`, `LC_MESSAGES`, then `LANG` |
| `NO_COLOR` | Plain, uncoloured terminal welcome |
| `XDG_STATE_HOME` | Base of the local state directory on any system, when set to an absolute path |

The Skill follows the language of your conversation, whatever these variables say.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.