# CLI

> The xholic command line: every Xholic action from your terminal, scripts, CI and coding agents, with browser login or an API key.

Source: https://docs.xholic.ai/cli/

The `xholic` CLI runs every Xholic [action](/actions/) from a terminal. It is built from the same definitions as the API and MCP server, so commands, inputs and errors match exactly.

```bash
npm i -g xholic
xholic login
xholic whoami
```

## Signing in

| Command | What it does |
| --- | --- |
| `xholic login` | Opens your browser to approve the CLI (OAuth with PKCE). |
| `xholic login --no-browser` | Prints the sign-in URL instead of opening a browser. |
| `xholic login --api-key xhk_…` | Stores an API key instead. `echo "$KEY" \| xholic login --api-key -` reads it from stdin. |
| `xholic logout` | Forgets the stored sign-in or key. |
| `xholic whoami` | Who you're signed in as, and the X accounts you can act on. |

`xholic login` prints a login code such as `K7QM-2XPD`. The consent page in your browser shows the same code: approve only if they match. The CLI starts with Read and Write; the first time a command needs Publish, it prints a link to allow it.

Credentials are saved in `~/.config/xholic/config.json`, readable only by you.

**In CI**, set `XHOLIC_API_KEY` to a key from **Settings → API / MCP / CLI**. When it is set it always wins, so no login is needed.

## Commands

Every action is `xholic <area> <action>`, with one flag per input field in kebab-case:

```bash
xholic posts schedule \
  --text "Shipping beats planning." \
  --scheduled-at 2026-11-03T09:00 \
  --timezone Europe/London

xholic queue list
xholic analytics summary --account @brandaccount
xholic x search --query "ai agents" --output json | jq '.data'
```

- `scheduledAt` becomes `--scheduled-at`; `postId` becomes `--post-id`.
- Booleans: `--flag` for true, `--no-flag` for false.
- Lists: repeat the flag, or separate short values such as IDs and handles with commas.
- Objects (such as `--automation`): pass JSON.
- `xholic <area> --help` lists an area's commands; `xholic <area> <action> --help` lists a command's flags.

The full list is in [CLI commands](/cli/commands/), and every flag's type is in the [actions reference](/actions/).

## Flags

These work on every command where they apply:

| Flag | What it does |
| --- | --- |
| `--account @handle` | X account to act on. Defaults to the connection's default account. |
| `--dry-run` | Changes only: show what would happen without doing it. |
| `--idempotency-key <key>` | Changes only: repeating a call with the same key returns the first result. |
| `--estimate` | Xholic AI actions: print the credit quote and stop. |
| `--yes` | Xholic AI actions: confirm the quoted credits without asking. |
| `--json '<object>'` | The whole input as one JSON object. Individual flags override its fields. |
| `--output json\|text` | Readable text on a terminal and JSON when piped, by default. |
| `--api <url>` | API base URL. Default `https://api.xholic.ai`. |
| `--help`, `-h` | Help for any command. |

Without `--yes`, an action that uses Xholic AI shows the quote and asks before spending anything. In a non-interactive shell it stops instead, so a script can never spend credits by accident.

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success |
| `1` | Error (see the message and its `code`) |
| `2` | Confirmation needed: an Xholic AI quote waits for `--yes` |
| `3` | Not signed in, invalid credential or missing scope |
| `4` | Rate limited or the plan's X data limit reached |