x-cli

Table of content

social media platforms are allergic to terminal access. they want you locked in their web UI, scrolling endlessly, clicking ads. x-cli is the antidote.

what it is

x-cli (15 ★) by Infatoshi is a terminal-native interface to Twitter/X API v2. post tweets, search, read timelines, manage bookmarks, check metrics — all from the command line.

accepts tweet URLs or IDs interchangeably. outputs JSON, plain text, markdown, or human-readable panels. designed to work seamlessly with x-mcp (same author) — if you already have x-mcp configured, x-cli works with zero additional setup.

built for humans who hate web UIs and agents who can’t click buttons.

why it matters

AI agents don’t scroll Twitter. they can’t like posts with a mouse. they can’t search for context by clicking around.

but they can execute shell commands:

x-cli tweet search "from:elonmusk openai" --max 10
x-cli like <tweet-url>
x-cli me bookmarks --max 50

x-cli makes Twitter/X agent-accessible. which means your agents can:

this isn’t about replacing the Twitter app. it’s about making Twitter data and actions available to the tools you actually use: scripts, agents, CI/CD pipelines, cron jobs.

terminal-native Twitter means Twitter becomes a primitive in your automation stack.

how it works

authenticate once with Twitter API v2 credentials (consumer key/secret, access token/secret, bearer token). x-cli reads from ~/.config/x-cli/.env:

X_API_KEY=your_consumer_key
X_API_SECRET=your_secret_key
X_BEARER_TOKEN=your_bearer_token
X_ACCESS_TOKEN=your_access_token
X_ACCESS_TOKEN_SECRET=your_access_token_secret

then it’s just commands:

# post a tweet
x-cli tweet post "shipped a new feature"

# post with a poll
x-cli tweet post --poll "Yes,No" "do you like polls?"

# search
x-cli tweet search "machine learning" --max 20

# read timeline
x-cli user timeline elonmusk --max 10

# like and retweet
x-cli like <tweet-url>
x-cli retweet <tweet-url>

# manage bookmarks
x-cli me bookmarks
x-cli me bookmark <tweet-url>
x-cli me unbookmark <tweet-url>

# get metrics
x-cli tweet metrics <tweet-id>

accepts URLs or IDs — paste https://x.com/user/status/123 or just 123. same result.

output modes:

verbose mode (-v) shows full metadata: timestamps, metrics, pagination tokens. compact mode (default) strips it down to essentials.

zero-config if you use x-mcp

if you already have x-mcp set up, x-cli uses the same credentials:

mkdir -p ~/.config/x-cli
ln -s /path/to/x-mcp/.env ~/.config/x-cli/.env

same auth, two tools. x-mcp for Model Context Protocol integrations, x-cli for terminal automation. no duplication, no extra setup.

this is the right way to build tooling: shared primitives, composable layers.

agent-friendly design

x-cli was built with automation in mind from the start:

example agent workflow:

# agent searches for recent context
RESULTS=$(x-cli -j tweet search "AI agents" --max 5)

# agent parses JSON
echo "$RESULTS" | jq -r '.data[].text'

# agent bookmarks relevant thread
x-cli me bookmark <tweet-url>

# agent posts update
x-cli tweet post "interesting discussion about AI agents: <link>"

the JSON output is clean API v2 responses — agents can parse it without custom wrappers.

install

# from source
git clone https://github.com/INFATOSHI/x-cli.git
cd x-cli
uv tool install .

# or from PyPI (once published)
uv tool install x-cli

setup:

  1. create an app in X Developer Portal
  2. set permissions to “read and write”
  3. generate access tokens
  4. save credentials to ~/.config/x-cli/.env
  5. test: x-cli me mentions --max 5

fits the self.md thesis

the self.md thesis: your repo is your operating system. tools that speak plaintext and git win.

x-cli fits this model. it doesn’t try to be a platform. it’s infrastructure. it makes Twitter data and actions available as terminal primitives.

which means:

compare to alternatives:

this is the pattern: take a proprietary platform, flatten it into shell commands, output structured text. now it’s composable. now agents can use it.