Obi CLI overview

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

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:

{
  "schemaVersion": 1,
  "ok": true,
  "command": "status",
  "mode": "product",
  "data": {}
}

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

{
  "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:

{
  "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.

Get started

How Obi works

CLI reference

Account

For AI agents

Obi CLI overview

Help and version

Global options

JSON output

Exit codes

Credentials and local state

Environment variables

​Help and version

​Global options

​JSON output

​Exit codes

​Credentials and local state

​Environment variables

Help and version

Global options

JSON output

Exit codes

Credentials and local state

Environment variables