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/paperfoot/xmaster-cli/main/install.sh | sh

Homebrew:

brew tap paperfoot/tap
brew install xmaster

Cargo (crates.io):

cargo install xmaster

From source:

cargo install --git https://github.com/paperfoot/xmaster-cli

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:

X removed Likes, Follows, and Quote-post writes from all self-serve API tiers on April 20, 2026. like/follow return a clear error on non-Enterprise keys; quote posts fall back to the web session automatically.

Every command returns JSON when piped (or with --json); list commands also support --csv for spreadsheet-ready output. Exit codes are semantic: 0 success, 1 runtime error, 2 config/billing 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

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

article preview and article draft are for X Articles, not long posts / Note Tweets. Drafts use Markdown and map to the native Article surface: # title, ##/### headings, **bold**, *italic*, ~~strikethrough~~, indentation/quotes, numbered/bulleted lists, links, images, video/GIF directives, and embedded X posts. Use ::video[Caption](https://github.com/199-biotechnologies/xmaster/blob/main/clip.mp4), ::gif[Caption](https://github.com/199-biotechnologies/xmaster/blob/main/loop.gif), ::post(https://x.com/user/status/123), or ::article(https://x.com/i/article/123) for media and embeds that Markdown does not model directly. Native draft creation uses X's private web Article entity endpoint (ArticleEntityDraftCreate) with browser cookies from xmaster config web-login; it saves a draft and does not publish. Add --api to create the draft through the official X API v2 Articles endpoint instead (added June 2026 — plain OAuth keys, no cookies; cover images stay in the body). xmaster article publish <article_id> then publishes it via the official endpoint and returns the created post ID.

Reading and Discovery

Search

Social Graph

Direct Messages

Scheduling

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

bookmarks sync archives content in SQLite. If the original tweet gets deleted, your copy survives.

Engagement Intelligence

engage inbox is the post-launch check: it pulls root replies, quote tweets, and replies under those quote tweets, then ranks likely reply-back opportunities as a reciprocity heuristic.

The opportunity scorer ranks targets by reciprocity, reply ROI, size fit (adaptive to your follower count), topicality, and freshness.

Pre-Flight Analysis

analyze estimates 9 proxy signals aligned with the 2026 X algorithm and scores per goal (replies, quotes, shares, follows, impressions). For drafts above 500 chars it also runs long-form heuristics (preview-card hook on the first 280 chars, scannability, payoff density, dwell sweet-spot 500–2000 chars) — informed by the Jan 2026 $1M Article Contest results. Run xmaster agent-info for the full long-form pattern set including timing, structure, and a nanaban pointer for cover-image generation.

Lists

Moderation

System

For AI Agents

XMaster is built for AI agents from day one. Every command supports --json and returns structured envelopes with semantic exit codes.

# JSON output (auto-enabled when piped)
xmaster --json post "Hello from my agent"
xmaster post "Hello" | jq '.data.id'

Response envelope:

{
  "version": "1",
  "status": "success",
  "data": { "..." },
  "metadata": {
    "elapsed_ms": 342,
    "provider": "x_api"
  }
}

Exit codes: 0 = success, 1 = runtime error, 2 = config error, 3 = auth missing, 4 = rate limited.

Agent discovery:

xmaster agent-info --json
# Returns: 64 commands, 18 capabilities, 15 algorithm weights,
# measurement coverage, workflow handoffs, writing style config

Pre-flight analysis:

xmaster analyze "your tweet" --goal replies --json
# Returns per-signal scores and per-goal scores (0-100)

Works with: Claude Code, OpenClaw, or any agent that can shell out and parse JSON.

Configuration

Config lives at ~/.config/xmaster/config.toml on all platforms. Override with XMASTER_CONFIG_DIR.

xmaster config show       # View current config (keys masked)
xmaster config check      # Validate credentials
xmaster config set K V    # Set a value
xmaster config get K      # Read a value

Environment variables override the config file. Use XMASTER_ prefix with double underscore for nesting:

export XMASTER_KEYS__API_KEY=your-api-key
export XMASTER_KEYS__API_SECRET=your-api-secret
export XMASTER_KEYS__ACCESS_TOKEN=your-access-token
export XMASTER_KEYS__ACCESS_TOKEN_SECRET=your-access-token-secret
export XMASTER_KEYS__XAI=your-xai-key

Building from Source

git clone https://github.com/paperfoot/xmaster-cli
cd xmaster
cargo build --release
# Binary at target/release/xmaster

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

License

MIT