x-cli

A command-line tool for the X (Twitter) API v2. Look up users, fetch tweets, sync bookmarks, and manage a follow list from the terminal with agent-friendly output.

Install globally:

npm install -g @patrikbreitenmoser/x-cli

Requirements

• Node.js 18 or newer
• An X developer app with OAuth 2.0 enabled

Create your app at developer.x.com.

Required scopes:

• bookmark.read
• tweet.read
• users.read
• offline.access

Install

The package name is @patrikbreitenmoser/x-cli, but the command you run is always x-cli.

Run without installing globally

npx @patrikbreitenmoser/x-cli --help

Install globally

npm install -g @patrikbreitenmoser/x-cli
x-cli --help

Install in a project

npm install @patrikbreitenmoser/x-cli
npx x-cli --help

Quick Start

1. Authenticate with your X app credentials:

   x-cli auth login

2. Complete the browser-based OAuth authorization flow.

3. Start using the CLI:

   x-cli auth status
   x-cli user elonmusk
   x-cli tweets elonmusk --limit 10

Before login, make sure ~/.x-cli/credentials.json contains your X app client ID:

{
  "clientId": "YOUR_CLIENT_ID"
}

Authentication

x-cli auth login opens a browser window for OAuth authorization. It reads clientId from ~/.x-cli/credentials.json. If your app also requires a client secret for token exchange, keep clientSecret in the same file or pass --client-secret. After a successful login, credentials and tokens are stored in ~/.x-cli/credentials.json with owner-only permissions. Access tokens refresh automatically.

Useful auth commands:

x-cli auth status
x-cli auth logout

Common Commands

Home view

x-cli
x-cli --format json

Running x-cli with no subcommand prints a compact dashboard with auth status, follow-list count, sync state, and suggested next steps.

User lookup

x-cli user elonmusk
x-cli user alice bob charlie

Tweets

x-cli tweets elonmusk --limit 10
x-cli tweets alice bob --since 2026-01-01
x-cli tweets elonmusk --no-replies --no-retweets
x-cli tweets alice --fields url,attachments
x-cli tweets alice --full

Bookmarks

x-cli bookmarks
x-cli bookmarks --limit 50
x-cli bookmarks --all
x-cli bookmarks --all --full

bookmarks uses incremental sync by default. After the first run, it only returns bookmarks newer than the last saved bookmark ID.

Follow list

Manage a local follow list. When you run tweets with no targets, x-cli uses this list automatically.

x-cli follows add alice bob naval
x-cli follows remove bob
x-cli follows list
x-cli tweets

When x-cli tweets runs against the follow list, it also tracks the last sync timestamp and fetches only newer tweets on later runs unless you pass --since.

Output

All command results are written as structured data to stdout. The default format is TOON for lower token usage; use --format json for compatibility with JSON consumers. Status and diagnostic messages go to stderr.

x-cli tweets elonmusk
x-cli tweets elonmusk --format json | jq '.tweets[].text'
x-cli bookmarks --all --format json > bookmarks.json

Most list commands now default to compact fields. Use --fields <name,...> or --full to request expanded output.

Hooks

x-cli can install managed Codex and Claude session-start hooks if you want agents to start with a compact dashboard. Hook changes are explicit:

x-cli hooks status
x-cli hooks install
x-cli hooks uninstall

Data Storage

All local state is stored in ~/.x-cli/:

| File | Contents | |------|----------| | credentials.json | OAuth tokens and client credentials | | sync-state.json | Last sync timestamps and bookmark cursor | | follows.json | Local follow list |

The directory is created with mode 0700. Files are written with mode 0600.

Developer Setup

If you want to work on the CLI itself instead of consuming the npm package:

npm install
npm run build

Useful development commands:

npm run dev -- --help
npm run dev -- auth login
npm run dev -- tweets elonmusk --limit 10
node dist/index.js --help
npm test

Notes:

• npm run build compiles TypeScript to dist/ and makes dist/index.js executable.
• npm run dev -- ... runs the TypeScript entrypoint directly with tsx.
• prepublishOnly runs npm run build before publishing.

License

MIT