# X CLI > Usage reference for the x CLI, a read-only X (Twitter) API client for the terminal built on Bun. Covers all commands, flags, authentication, and common usage patterns. Use when working with or answering questions about the x CLI. - Skill: `abpai/x-cli` (Agent Skill, multi-file: 12 files) - Install (CLI): `npx skillmds@latest add abpai/x-cli` - Raw SKILL.md: https://api.skillmd.com/api/skills/abpai/x-cli/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: abpai (https://skillmd.com/u/abpai) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/abpai/x-cli --- # 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). ```bash x timelines [options] ``` | Flag | Short | Default | Description | | ------------------- | ----- | ------- | -------------------------------------------------------------- | | `--max-results ` | `-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 ` | | `auto` | Inline image mode for `--pretty`: `auto`, `on`, `off` | | `--image-width ` | | `40` | Image width in terminal cells (20-80) | | `--max-images ` | | `4` | Max inline images to render (0-12) | **Auth:** OAuth 2.0 User Context (`X_USER_ACCESS_TOKEN`) ```bash 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. ```bash x bookmarks [options] ``` | Flag | Short | Default | Description | | ------------------- | ----- | ------- | ------------------------------------- | | `--max-results ` | `-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`) ```bash x bookmarks -m 5 --pretty # pretty terminal view x bookmarks -m 100 # full JSON for agent piping ``` ### search Search recent tweets. ```bash x search [options] ``` | Flag | Short | Default | Description | | ------------------- | ----- | ------- | ----------------------------------- | | `--max-results ` | `-m` | `25` | Number of results to return (5-100) | | `--pretty` | | `false` | Human-readable terminal output | **Auth:** Bearer Token (`X_BEARER_TOKEN`) ```bash 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. ```bash x following [options] ``` | Flag | Short | Default | Description | | ------------------- | ----- | ------- | --------------------------------- | | `--max-results ` | `-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`) ```bash x following -m 50 # JSON list of followed users ``` ### setup Guided credential setup for X API access. Alias: `init`. ```bash x setup [options] ``` | Flag | Default | Description | | -------------------------- | ---------------------- | -------------------------------------- | | `--env-file ` | `~/.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 | ```bash 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 `--pretty` mode (timelines only). `auto` detects Kitty/Ghostty support; `on` forces rendering; `off` disables it. ## Common Patterns **Agent JSON piping:** ```bash x timelines -m 25 | jq '.data[].text' x search "topic" -m 10 | your-agent --stdin ``` **Human pretty output:** ```bash x timelines -m 5 --pretty --images auto x bookmarks -m 5 --pretty x search "long running agents" -m 5 --pretty ``` **CI / non-interactive setup:** ```bash 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` |