abpai x CLI
Read-only X API client for the terminal, built on Bun.
Commands
timelines
Fetch the authenticated user following timeline (UI-like by default).
x timelines [options]
| Flag | Short | Default | Description |
|---|---|---|---|
--max-results <n> |
-m |
25 |
Number of tweets to return (5-100) |
--all |
false |
Include replies and reposts (raw reverse-chronological output) | |
--pretty |
false |
Human-readable terminal output | |
--images <mode> |
auto |
Inline image mode for --pretty: auto, on, off |
|
--image-width <n> |
40 |
Image width in terminal cells (20-80) | |
--max-images <n> |
4 |
Max inline images to render (0-12) |
Auth: OAuth 2.0 User Context (X_USER_ACCESS_TOKEN)
x timelines -m 10 --pretty # pretty terminal view
x timelines -m 5 --pretty --images on # with inline Kitty images
x timelines --all -m 50 # raw JSON, all tweets
bookmarks
Fetch the authenticated user bookmarks.
x bookmarks [options]
| Flag | Short | Default | Description |
|---|---|---|---|
--max-results <n> |
-m |
25 |
Number of bookmarks to return (5-100) |
--pretty |
false |
Human-readable terminal output |
Auth: OAuth 2.0 User Context (X_USER_ACCESS_TOKEN)
x bookmarks -m 5 --pretty # pretty terminal view
x bookmarks -m 100 # full JSON for agent piping
search
Search recent tweets.
x search <query...> [options]
| Flag | Short | Default | Description |
|---|---|---|---|
--max-results <n> |
-m |
25 |
Number of results to return (5-100) |
--pretty |
false |
Human-readable terminal output |
Auth: Bearer Token (X_BEARER_TOKEN)
x search "openai bun" -m 10 --pretty # pretty search results
x search long running agents # multi-word query, JSON output
following
Fetch the authenticated user following list.
x following [options]
| Flag | Short | Default | Description |
|---|---|---|---|
--max-results <n> |
-m |
25 |
Number of users to return (5-100) |
Auth: OAuth 1.0a (X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET)
x following -m 50 # JSON list of followed users
setup
Guided credential setup for X API access. Alias: init.
x setup [options]
| Flag | Default | Description |
|---|---|---|
--env-file <path> |
~/.config/x-cli/.env |
Path for credential file |
--from-env |
false |
Use existing environment values |
--no-input |
false |
Disable interactive prompts |
--oauth2 / --no-oauth2 |
--oauth2 |
Run or skip OAuth 2.0 user-token setup |
--overwrite |
false |
Overwrite existing env file |
x setup # interactive guided setup
x setup --no-input # non-interactive from env vars
x setup --no-oauth2 # skip OAuth 2.0 (following + search only)
x setup --overwrite # re-mint tokens, overwrite env file
Authentication
| Variable | Auth Flow | Used By |
|---|---|---|
X_API_KEY |
OAuth 1.0a | following |
X_API_SECRET |
OAuth 1.0a | following |
X_ACCESS_TOKEN |
OAuth 1.0a | following |
X_ACCESS_TOKEN_SECRET |
OAuth 1.0a | following |
X_BEARER_TOKEN |
App-Only (OAuth 2.0) | search |
X_USER_ACCESS_TOKEN |
OAuth 2.0 User Context | bookmarks, timelines |
X_USER_REFRESH_TOKEN |
OAuth 2.0 refresh | automatic token renewal |
X_CLIENT_ID |
OAuth 2.0 | token refresh, setup |
X_CLIENT_SECRET |
OAuth 2.0 | token refresh, setup |
Config precedence: process env vars (highest) > shared env file (~/.config/x-cli/.env). Override the shared path with X_CLI_SHARED_ENV_PATH.
Token refresh: When X_USER_REFRESH_TOKEN and X_CLIENT_ID are set, the CLI auto-refreshes on 401 and persists new tokens to the shared env file.
Output Modes
- JSON (default) — structured output, ideal for piping to agents or
jq. --pretty— human-readable terminal rendering (timelines, bookmarks, search).--images— inline Kitty-protocol image previews in--prettymode (timelines only).autodetects Kitty/Ghostty support;onforces rendering;offdisables it.
Common Patterns
Agent JSON piping:
x timelines -m 25 | jq '.data[].text'
x search "topic" -m 10 | your-agent --stdin
Human pretty output:
x timelines -m 5 --pretty --images auto
x bookmarks -m 5 --pretty
x search "long running agents" -m 5 --pretty
CI / non-interactive setup:
export X_API_KEY=... X_API_SECRET=... X_BEARER_TOKEN=...
x setup --no-input --no-oauth2
Development
| Script | Command |
|---|---|
| Dev (watch) | bun run dev |
| Start | bun run start |
| Build | bun run build |
| Lint | bun run lint |
| Format | bun run format |
| Typecheck | bun run typecheck |
| Lint + typecheck | bun run check |
| Test | bun run test |
| Test (watch) | bun run test:watch |