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