CLI

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

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

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:

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, and every flag’s type is in the actions reference.

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