XMaster
The X/Twitter CLI for developers and AI agents
Post, reply, like, retweet, DM, search, schedule, and analyze -- all from your terminal. XMaster is a single Rust binary that wraps the X API v2, xAI/Grok search, and a web session fallback into one tool. It outputs structured JSON for AI agents and readable tables for humans.
Install | How It Works | Commands | Contributing
Why This Exists
I wanted my AI agents to handle X for me. Find posts in my niche, draft replies in my voice, track what works. Not for spamming -- just a less tedious way to stay engaged when I'd rather be building things.
Most X tools make you pick between the official API and scraping. XMaster gives you both, plus the parts nobody else builds: pre-flight post analysis, engagement scoring, reply bypass, local scheduling, and a bookmarks archive that survives tweet deletions.
Install
One-liner (macOS / Linux):
curl -fsSL https://raw.githubusercontent.com/199-biotechnologies/xmaster/master/install.sh | sh
Homebrew:
brew tap 199-biotechnologies/tap
brew install xmaster
Cargo (crates.io):
cargo install xmaster
From source:
cargo install --git https://github.com/199-biotechnologies/xmaster
Quick Start
# 1. Get your X API keys from https://developer.x.com
# 2. Configure credentials
xmaster config set keys.api_key YOUR_API_KEY
xmaster config set keys.api_secret YOUR_API_SECRET
xmaster config set keys.access_token YOUR_ACCESS_TOKEN
xmaster config set keys.access_token_secret YOUR_ACCESS_TOKEN_SECRET
# 3. Verify setup
xmaster config check
# 4. Post
xmaster post "Hello from xmaster"
Optional extras:
xmaster config set keys.xai YOUR_XAI_KEY # AI-powered search via xAI/Grok
xmaster config web-login # Enable reply bypass (auto-captures browser cookies)
xmaster config set style.voice "your style here" # Agents write in your voice
xmaster config set account.premium true # 25k char limit instead of 280
How It Works
XMaster has three backends behind one CLI:
| Backend | Auth | Used for | |---------|------|----------| | X API v2 | OAuth 1.0a | Posting, likes, retweets, DMs, search, timelines, follows | | xAI / Grok | Bearer token | AI-powered semantic search, trending topics | | Web GraphQL | Browser cookies | Reply bypass when X blocks API replies to strangers |
Every command returns JSON when piped (or with --json). Exit codes are semantic: 0 success, 1 runtime error, 2 config error, 3 auth missing, 4 rate limited. Your agent always knows what happened.
┌─────────────────────────────────────────────┐
│ CLI Layer │
│ clap + comfy-table (--json / human) │
├─────────────────────────────────────────────┤
│ Command Router + Pre-flight │
│ Analyze, score, cannibalization guard │
├──────────┬──────────────┬───────────────────┤
│ X API v2 │ xAI / Grok │ Web GraphQL │
│(OAuth1.0a│(Bearer token)│ (Cookie auth + │
│ Post,Like│ AI search, │ transaction ID) │
│ RT, DM, │ Trending, │ Reply fallback │
│ Search, │ Semantic │ when API blocks │
│ Timeline)│ search │ replies │
├──────────┴──────────────┴───────────────────┤
│ Rate Limiter │ Intel Store │ Scheduler │
│ (header-based)│ (SQLite) │ (launchd) │
├─────────────────────────────────────────────┤
│ Config (figment) │
│ TOML + env vars + browser cookies │
└─────────────────────────────────────────────┘
Commands
Posting and Engagement
| Command | What it does | Example |
|---------|-------------|---------|
| post | Post text, media, replies, quotes, polls | xmaster post "Hello world" |
| reply | Reply to a post (auto-bypasses API restrictions) | xmaster reply 1234567890 "Great point" |
| thread | Post a multi-tweet thread | xmaster thread "First" "Second" "Third" |
| delete | Delete a post | xmaster delete 1234567890 |
| like | Like a tweet (ID or URL) | xmaster like 1234567890 |
| unlike | Unlike a tweet | xmaster unlike 1234567890 |
| retweet | Retweet a tweet | xmaster retweet 1234567890 |
| unretweet | Undo a retweet | xmaster unretweet 1234567890 |
| bookmark | Bookmark a tweet | xmaster bookmark 1234567890 |
| unbookmark | Remove a bookmark | xmaster unbookmark 1234567890 |
Post options:
xmaster post "Great point!" --reply-to 1234567890 # Reply
xmaster post "This is big" --quote 1234567890 # Quote tweet
xmaster post "Check this" --media photo.jpg # Attach media (up to 4)
xmaster post "Best language?" --poll "Rust,Go,Python" # Create a poll
xmaster like https://x.com/user/status/1234567890 # URLs work too
Reading and Discovery
| Command | What it does | Example |
|---------|-------------|---------|
| read | Full post lookup (text, author, metrics, media) | xmaster read 1234567890 |
| replies | Get replies on a post | xmaster replies 1234567890 -c 30 |
| metrics | Detailed engagement metrics | xmaster metrics 1234567890 |
| timeline | Home or user timeline | xmaster timeline --user elonmusk --since 24h |
| mentions | Your mentions | xmaster mentions -c 20 |
| user | User profile info | xmaster user elonmusk |
| me | Your own profile | xmaster me |
Search
| Command | What it does | Example |
|---------|-------------|---------|
| search | X API v2 search (structured, filterable) | xmaster search "rust lang" --mode recent |
| search-ai | AI-powered search via xAI/Grok | xmaster search-ai "latest AI news" |
| trending | Trending topics by region | xmaster trending --region US |
Social Graph
| Command | What it does | Example |
|---------|-------------|---------|
| follow | Follow a user | xmaster follow elonmusk |
| unfollow | Unfollow a user | xmaster unfollow elonmusk |
| followers | List followers | xmaster followers elonmusk -c 50 |
| following | List who a user follows | xmaster following elonmusk -c 50 |
Direct Messages
| Command | What it does | Example |
|---------|-------------|---------|
| dm send | Send a DM | xmaster dm send alice "Hey!" |
| dm inbox | View DM inbox | xmaster dm inbox -c 20 |
| dm thread | View a DM conversation | xmaster dm thread CONV_ID |
Scheduling
| Command | What it does | Example |
|---------|-------------|---------|
| schedule add | Schedule a post for later | xmaster schedule add "text" --at "2026-03-24 09:00" |
| schedule add --at auto | Auto-pick best posting time | xmaster schedule add "text" --at auto |
| schedule list | List scheduled posts | xmaster schedule list --status pending |
| schedule cancel | Cancel a scheduled post | xmaster schedule cancel sched_abc123 |
| schedule fire | Execute due posts (for cron) | xmaster schedule fire |
| schedule setup | Install launchd auto-scheduler | xmaster schedule setup |
Posts are stored in local SQLite. No X Ads API needed. The launchd daemon fires every 5 minutes on macOS. Use --at auto to pick the best time from your engagement history.
Bookmark Intelligence
| Command | What it does | Example |
|---------|-------------|---------|
| bookmarks list | List recent bookmarks | xmaster bookmarks list -c 20 |
| bookmarks sync | Archive bookmarks locally (survives deletions) | xmaster bookmarks sync -c 200 |
| bookmarks search | Search your archive | xmaster bookmarks search "longevity" |
| bookmarks export | Export as markdown | xmaster bookmarks export -o bookmarks.md |
| bookmarks digest | Weekly summary | xmaster bookmarks digest -d 7 |
bookmarks sync archives content in SQLite. If the original tweet gets deleted, your copy survives.
Engagement Intelligence
| Command | What it does | Example |
|---------|-------------|---------|
| engage recommend | Find high-ROI reply targets | xmaster engage recommend --topic "AI" -c 10 |
| engage feed | Fresh posts from large accounts | xmaster engage feed "AI agents" --min-followers 5000 |
| engage watchlist add | Track accounts without following | xmaster engage watchlist add elonmusk |
| engage watchlist list | List watched accounts | xmaster engage watchlist list |
The opportunity scorer ranks targets by reciprocity, reply ROI, size fit (adaptive to your follower count), topicality, and freshness.
Pre-Flight Analysis
| Command | What it does | Example |
|---------|-------------|---------|
| analyze | Score a post before publishing | xmaster analyze "your text" --goal replies |
| suggest best-time | Best posting time from history | xmaster suggest best-time |
| suggest next-post | Cannibalization guard | xmaster suggest next-post |
| `r