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`
`report daily`	Daily performance digest	`xmaster report daily`
`report weekly`	Weekly performance digest	`xmaster report weekly`
`track run`	Snapshot recent post metrics	`xmaster track run`
`track followers`	Track follower changes	`xmaster track followers`
`track growth`	Follower growth history	`xmaster track growth -d 30`
`inspire`	Browse your discovered posts library	`xmaster inspire --topic "longevity"`

analyze estimates 9 proxy signals aligned with the 2026 X algorithm and scores per goal (replies, quotes, shares, follows, impressions).

Lists

Command	What it does	Example
`lists create`	Create a list	`xmaster lists create "AI Builders"`
`lists add`	Add user to a list	`xmaster lists add LIST_ID username`
`lists timeline`	View a list timeline	`xmaster lists timeline LIST_ID`
`lists mine`	View your lists	`xmaster lists mine`

Moderation

Command	What it does	Example
`block` / `unblock`	Block or unblock a user	`xmaster block spammer123`
`mute` / `unmute`	Mute or unmute a user	`xmaster mute username`
`hide-reply` / `unhide-reply`	Hide replies on your posts	`xmaster hide-reply 1234567890`

System

Command	What it does	Example
`config show`	View config (keys masked)	`xmaster config show`
`config check`	Validate credentials	`xmaster config check`
`config web-login`	Capture browser cookies for reply bypass	`xmaster config web-login`
`agent-info`	Machine-readable capabilities for AI agents	`xmaster agent-info --json`
`rate-limits`	Check API quota status	`xmaster rate-limits`
`update`	Self-update from GitHub releases	`xmaster update`

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/199-biotechnologies/xmaster
cd xmaster
cargo build --release
# Binary at target/release/xmaster

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

License

MIT

Built by Boris Djordjevic at 199 Biotechnologies | Paperfoot AI

If this is useful to you:

Name		Name	Last commit message	Last commit date
Latest commit History 102 Commits
.claude		.claude
.github/workflows		.github/workflows
.research		.research
docs		docs
skill		skill
src		src
tests		tests
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
config.example.toml		config.example.toml
install.sh		install.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

XMaster

Why This Exists

Install

Quick Start

How It Works

Commands

Posting and Engagement

Reading and Discovery

Search

Social Graph

Direct Messages

Scheduling

Bookmark Intelligence

Engagement Intelligence

Pre-Flight Analysis

Lists

Moderation

System

For AI Agents

Configuration

Building from Source

Contributing

License

About

Uh oh!

Releases 21

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

XMaster

Why This Exists

Install

Quick Start

How It Works

Commands

Posting and Engagement

Reading and Discovery

Search

Social Graph

Direct Messages

Scheduling

Bookmark Intelligence

Engagement Intelligence

Pre-Flight Analysis

Lists

Moderation

System

For AI Agents

Configuration

Building from Source

Contributing

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 21

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages