<p align="center">
<h1 align="center">xmaster</h1>
</p>
<p align="center">
<strong>Enterprise-grade X/Twitter CLI — dual backend, agent-first, blazing fast.</strong><br>
<em>X API v2 + xAI Grok search in one binary. Built for <a href="https://github.com/openclaw">OpenClaw</a> agents, Claude Code, and humans.</em>
</p>
<p align="center">
<a href="#install">Install</a> ·
<a href="#quick-start">Quick Start</a> ·
<a href="#commands">Commands</a> ·
<a href="#for-ai-agents">For AI Agents</a> ·
<a href="#configuration">Configuration</a>
</p>
---
A single Rust binary that gives you full control over X/Twitter: post, reply, like, retweet, DM, search, bookmark, follow, schedule, and more. Two search backends — X API v2 for structured queries and xAI/Grok for AI-powered semantic search. Designed from day one for AI agents with structured JSON output, semantic exit codes, and auto-JSON when piped.
```bash
xmaster post "Hello from the command line"
```
---
## Why xmaster
Every X CLI makes you choose between official API features and AI-powered search. **xmaster** gives you both:
- **Dual backend** — X API v2 (OAuth 1.0a) for posting, engagement, DMs, and structured search. xAI/Grok for AI-powered semantic search and trending topics.
- **Agent-first** — Structured JSON output, semantic exit codes (0-4), machine-readable `agent-info` command, auto-JSON when piped. Built for AI agents that shell out.
- **Enterprise-grade** — Per-provider rate limiting (token bucket), OAuth 1.0a signing, media uploads, polls, quote tweets. Production-ready.
- **Single binary** — ~6MB, ~2ms startup, no Python, no Node, no Docker. Just `curl | sh` and go.
## Install
**One-liner (macOS / Linux):**
```bash
**Homebrew:**
```bash
brew tap 199-biotechnologies/tap
brew install xmaster
```
**Cargo (crates.io):**
```bash
cargo install xmaster
```
**Cargo (from source):**
```bash
cargo install --git https://github.com/199-biotechnologies/xmaster
```
## Quick Start
```bash
# 1. Get your X API keys from https://developer.x.com
# You need: API Key, API Secret, Access Token, Access Token Secret
# 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. (Optional) Add xAI key for AI-powered search
xmaster config set keys.xai YOUR_XAI_KEY
# 4. Verify setup
xmaster config check
# 5. Post your first tweet
xmaster post "Hello from xmaster"
```
## Commands
### Posting & Engagement
| `post` | Post a tweet (text, media, reply, quote, poll) | `xmaster post "Hello world"` |
| `delete` | Delete a tweet | `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` |
### Social Graph
| `follow` | Follow a user | `xmaster follow elonmusk` |
| `unfollow` | Unfollow a user | `xmaster unfollow elonmusk` |
| `followers` | List a user's followers | `xmaster followers elonmusk -c 50` |
| `following` | List who a user follows | `xmaster following elonmusk -c 50` |
### Timeline & Reading
| `timeline` | View home or user timeline | `xmaster timeline --user elonmusk` |
| `mentions` | View your mentions | `xmaster mentions -c 20` |
| `user` | Get user profile info | `xmaster user elonmusk` |
| `me` | Get your own profile info | `xmaster me` |
### Bookmark Intelligence
| `bookmarks list` | List recent bookmarks | `xmaster bookmarks list -c 20` |
| `bookmarks sync` | Archive bookmarks locally (survives tweet deletion) | `xmaster bookmarks sync -c 200` |
| `bookmarks search` | Search archived bookmarks | `xmaster bookmarks search "longevity"` |
| `bookmarks export` | Export as markdown | `xmaster bookmarks export -o bookmarks.md` |
| `bookmarks digest` | Weekly bookmark summary | `xmaster bookmarks digest -d 7` |
| `bookmarks stats` | Bookmark statistics | `xmaster bookmarks stats` |
The `sync` command archives bookmark content locally in SQLite. Even if the original tweet gets deleted, your local copy survives. Local search is instant, and the digest helps you actually read what you save. Sync regularly to keep your archive fresh.
### Search
| `search` | Search tweets (X API v2) | `xmaster search "rust lang" --mode recent` |
| `search-ai` | AI-powered search (xAI/Grok) | `xmaster search-ai "latest AI news"` |
| `trending` | Get trending topics (xAI) | `xmaster trending --region US` |
### Direct Messages
| `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
| `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 reschedule` | Change post time | `xmaster schedule reschedule sched_abc --at "2026-03-25 10:00"` |
| `schedule fire` | Execute due posts (cron) | `xmaster schedule fire` |
| `schedule setup` | Install launchd auto-scheduler | `xmaster schedule setup` |
Posts are stored locally in SQLite — no X Ads API needed, pure local scheduling. The `launchd` daemon fires every 5 minutes on macOS. Use `--at auto` to let xmaster pick the best posting time from your engagement history. Missed schedules are handled with a 5-minute grace period.
### System
| `config show` | Show config (keys masked) | `xmaster config show` |
| `config set` | Set a config value | `xmaster config set keys.api_key KEY` |
| `config check` | Validate credentials | `xmaster config check` |
| `agent-info` | Machine-readable capabilities | `xmaster agent-info` |
| `update` | Self-update from GitHub releases | `xmaster update` |
### Global Flags
| `--json` | Force JSON output (auto-enabled when piped) |
| `--quiet` | Suppress non-essential output |
### Post Options
```bash
# Reply to a tweet
xmaster post "Great point!" --reply-to 1234567890
# Quote tweet
xmaster post "This is important" --quote 1234567890
# Attach media (up to 4 files)
xmaster post "Check this out" --media photo.jpg --media chart.png
# Create a poll (24h default)
xmaster post "Best language?" --poll "Rust,Go,Python,TypeScript"
# Poll with custom duration (minutes)
xmaster post "Best language?" --poll "Rust,Go" --poll-duration 60
# Tweet ID or URL both work for engagement commands
xmaster like https://x.com/user/status/1234567890
```
### Search Options
```bash
# X API v2 search with mode
xmaster search "query" --mode recent # Recent tweets (default)
xmaster search "query" --mode popular # Popular tweets
xmaster search "query" -c 25 # Get 25 results
# AI-powered search with date filters
xmaster search-ai "CRISPR breakthroughs" --from-date 2026-01-01 --to-date 2026-03-01
xmaster search-ai "AI news" -c 20
# Trending topics
xmaster trending --region US --category technology
```
## For AI Agents
xmaster is built for AI agents from day one. Every command supports `--json` and structured error codes.
### JSON Output
```bash
# Force JSON output
xmaster --json post "Hello from my agent"
# Auto-JSON when piped
**Success envelope:**
```json
{
"version": "1",
"status": "success",
"data": { ... },
"metadata": {
"elapsed_ms": 342,
"provider": "x_api"
}
}
```
**Error envelope:**
```json
{
"status": "error",
"error": {
"code": "auth_missing",
"message": "Authentication missing: X API credentials not configured",
"suggestion": "Set X API credentials via env vars (XMASTER_API_KEY, etc.) or run: xmaster config set keys.api_key <key>"
}
}
```
### Exit Codes
| 0 | Success | Process results |
| 1 | Runtime error | Retry might help |
| 2 | Config error | Fix configuration |
| 3 | Auth missing | Set API key |
| 4 | Rate limited | Back off and retry |
### Agent Discovery
```bash
# Machine-readable capabilities and version
xmaster agent-info
```
### Integration Example (Claude Code Skill)
```bash
# In a Claude Code skill, xmaster works seamlessly:
RESULT=$(xmaster --json search "topic of interest" -c 5)
# Or for posting:
xmaster --json post "Automated insight" --reply-to "$TWEET_ID"
```
## Configuration
Config file lives at:
- **macOS:** `~/Library/Application Support/com.199biotechnologies.xmaster/config.toml`
- **Linux:** `~/.config/xmaster/config.toml`
Override with `XMASTER_CONFIG_DIR` env var.
```bash
xmaster config show # View current config (keys masked)
xmaster config check # Validate all credentials
xmaster config set K V # Set a value
```
### Environment Variables
Environment variables override the config file. Prefix: `XMASTER_`:
```bash
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
export XMASTER_SETTINGS_TIMEOUT=30
```
## Architecture
```
┌─────────────────────────────────────────────┐
│ CLI Layer │
│ clap + comfy-table (--json / human) │
├─────────────────────────────────────────────┤
│ Command Router │
│ Maps commands to providers + handlers │
├──────────────────┬──────────────────────────┤
│ X API v2 │ xAI / Grok │
│ (OAuth 1.0a) │ (Bearer token) │
│ Post, Like, │ AI search, │
│ RT, DM, Follow, │ Trending topics, │
│ Search, Timeline│ Semantic search │
├──────────────────┴──────────────────────────┤
│ Rate Limiter (governor) │
│ Token-bucket per provider │
├─────────────────────────────────────────────┤
│ Config (figment) │
│ TOML file + env vars + defaults │
└─────────────────────────────────────────────┘
```
### Key Design Decisions
- **OAuth 1.0a signing** — Full RFC 5849 implementation for X API v2. No SDK dependency.
- **Dual search** — `search` uses X API v2 (structured, filterable). `search-ai` uses xAI/Grok (semantic, AI-powered).
- **Token bucket rate limiting** — `governor` crate provides per-provider rate limiting to stay within API quotas.
- **Auto-JSON detection** — Output is JSON when piped, human-readable tables when in a terminal.
- **URL or ID** — Engagement commands accept both tweet URLs and raw IDs.
- **Media uploads** — Chunked upload flow with base64 encoding for images and video.
## Rate Limits
xmaster respects X API v2 rate limits with per-endpoint token bucket limiting:
| POST /tweets | 200 / 15 min (user) |
| GET /tweets/search | 450 / 15 min (app) |
| POST /likes | 200 / 15 min (user) |
| POST /retweets | 300 / 15 min (user) |
| GET /dm_conversations | 300 / 15 min (user) |
When rate limited, xmaster returns exit code 4 with a structured error including retry guidance.
## Updating
```bash
xmaster update # Self-update from GitHub releases
xmaster update --check # Check without installing
```
## Building from Source
```bash
git clone https://github.com/199-biotechnologies/xmaster
cd xmaster
cargo build --release
# Binary at target/release/xmaster
```
## License
MIT
---
Created by [Boris Djordjevic](https://x.com/longevityboris) — [199 Biotechnologies](https://github.com/199-biotechnologies) & Paperfoot AI (SG) Pte Ltd.