cryppadotta/xc

xc — X API v2 CLI

Use xc to interact with X (Twitter) via the official API. Pay-per-use with built-in cost tracking — no cookie scraping.

Installation

npm install -g @dotta/xc

Requires Node.js >= 18.

Setup / Authentication

xc requires OAuth 2.0 credentials from the X Developer Portal.

First-time setup

1. Go to developer.x.com or console.x.com
2. Create or select an app
3. Under OAuth 2.0 settings, copy your Client ID (and optionally Client Secret)
4. Set the Callback URL to http://127.0.0.1:3391/callback

# Interactive OAuth login (opens browser)
xc auth login --client-id <YOUR_CLIENT_ID>

# With client secret (enables automatic token refresh)
xc auth login --client-id <YOUR_CLIENT_ID> --client-secret <YOUR_SECRET>

# Check auth status
xc auth status

# App-only Bearer token (read-only, for streaming/usage)
xc auth token <BEARER_TOKEN>

Multiple accounts

xc auth login --account work --client-id <CLIENT_ID>
xc auth switch work
xc search "query" --account work

Config stored in ~/.xc/ (or $XC_CONFIG_DIR).

After upgrading: re-authenticate with xc auth login to grant new scopes (block, mute, tweet.moderate).

Quick Reference

# Identity
xc whoami                          # Who am I?
xc auth status                     # Auth status for all accounts

# Reading
xc get <post-id-or-url>              # Get a post by ID or URL (articles show full body)
xc get https://x.com/user/status/123 # Get a post by URL
xc search "query" -n 10            # Search recent posts (7-day window)
xc search "from:username" -n 5     # Search by author
xc user <username>                 # Look up user profile
xc usersearch "query"              # Search for users by keyword
xc timeline -n 10                  # Home timeline
xc timeline <username> -n 10       # User's posts
xc mentions                       # Your mentions timeline
xc mentions <username>             # Another user's mentions

# Posting
xc post "Hello world"              # Create a post
xc post "Reply" --reply <post-id>  # Reply to a post
xc post "Look" --quote <post-id>   # Quote a post
xc post "1/3" --thread "2/3" "3/3" # Post a thread
xc post "Photo" --media image.jpg  # Post with media (paid tier)
xc delete <post-id>                # Delete a post

# Engagement
xc like <post-id>                  # Like a post
xc unlike <post-id>                # Unlike a post
xc repost <post-id>                # Repost a post
xc unrepost <post-id>              # Undo a repost
xc bookmark <post-id-or-url>       # Bookmark a post and hydrate it into the local cache
xc unbookmark <post-id-or-url>     # Remove bookmark from X (cache entry stays local)

# Bookmarks
xc bookmarks remote                # List bookmarks directly from X
xc bookmarks remote --limit 50     # Larger remote page
xc bookmarks local sync            # Sync local bookmark cache (default 30-day post window)
xc bookmarks local sync --days 60  # Extend coverage window
xc bookmarks local sync --max-pages 3
xc bookmarks local list            # Browse cached bookmarks
xc bookmarks local list --author dotta --has-link
xc bookmarks local search "agent memory"
xc bookmarks local show <post-id-or-url>
xc bookmarks local status          # Local cache counts, sync window, oldest cached post
xc bookmarks local sql 'select count(*) from bookmark_posts'

# Engagement lookups
xc quotes <post-id>                # List quote tweets of a post
xc likes <post-id>                 # List users who liked a post
xc reposts <post-id>               # List users who reposted a post
xc liked                           # Posts you've liked
xc liked <username>                # Posts a user has liked

# Reply moderation
xc hide <post-id>                  # Hide a reply
xc unhide <post-id>                # Unhide a reply

# Social
xc followers <username> -n 20     # List followers
xc following <username> -n 20     # List following
xc follow <username>               # Follow a user
xc unfollow <username>             # Unfollow a user

# Blocking & Muting
xc block <username>                # Block a user
xc unblock <username>              # Unblock a user
xc blocked                         # List blocked users
xc mute <username>                 # Mute a user
xc unmute <username>               # Unmute a user
xc muted                           # List muted users

# Lists
xc lists                           # List owned lists
xc list view <list-id>             # View posts in a list
xc list create "My List"           # Create a list
xc list create "Private" --private # Create a private list
xc list update <id> --name "New"   # Update a list
xc list delete <id>                # Delete a list
xc list members <id>               # List members
xc list add <id> <username>        # Add member
xc list remove <id> <username>     # Remove member
xc list follow <id>                # Follow a list
xc list unfollow <id>              # Unfollow a list
xc list pin <id>                   # Pin a list
xc list unpin <id>                 # Unpin a list

# Trends
xc trends                          # Personalized trends
xc trends --global                 # Worldwide trends
xc trends <woeid>                  # Trends by location (WOEID)

# DMs (paid tier required)
xc dm list                         # List DM conversations
xc dm history <username>           # DM history with user
xc dm send <username> "message"    # Send a DM

# Streaming (requires Bearer Token auth)
xc stream rules                    # List stream rules
xc stream add "query"              # Add filter rule
xc stream remove <rule-id>         # Remove rule
xc stream clear                    # Remove all rules
xc stream connect                  # Connect to live stream

# Cost tracking
xc cost                            # Spending summary (1h/24h/7d/30d)
xc cost --daily                    # Day-by-day breakdown
xc cost log                        # Raw request log

# Budget
xc budget show                     # Current budget and spend
xc budget set --daily 2.00         # Set $2/day limit (warns when exceeded)
xc budget set --daily 5.00 --action block  # Block when over budget

# API usage
xc usage                           # X API usage stats (Bearer Token only)

Documentation

• X API v2 docs: https://docs.x.com/x-api/introduction

Important Notes

• Cost footer: Every command prints estimated cost. Suppress with --quiet.
• JSON output: Most commands support --json for machine-readable output.
• Multi-account: Use --account <name> on any command, or xc auth switch <name>.
• Rate limits: The X API has rate limits per endpoint. If you hit 429 errors, wait and retry.
• OAuth scopes: xc requests all scopes at login including block.read/write, mute.read/write, tweet.moderate.write. If you get 403 errors, re-authenticate to pick up new scopes.
• Paid tier features: DMs and media upload require a paid X API plan (pay-per-use or Basic+). Free tier returns 403.
• Bearer Token features: stream and usage commands require app-only Bearer Token auth (xc auth token <TOKEN>), not OAuth 2.0.
• Search minimum: X API returns a minimum of 10 results regardless of -n value.
• Local bookmark cache: xc bookmarks local ... reads from per-account SQLite at ~/.xc/bookmarks/<account>.db (or $XC_CONFIG_DIR/bookmarks/<account>.db).
• Bookmark sync strategy: local sync uses a cheap bookmark enumeration pass plus batched post hydration. Re-syncs skip already hydrated posts where possible.
• Bookmark sync cost: xc bookmarks local sync prints Request cost this sync: $... for the current run.
• Bookmark sync coverage: --days refers to bookmarked posts' created_at, not when you bookmarked them. X does not expose bookmarked_at.
• Bookmark API caveat: X's main bookmark endpoint may expose fewer bookmarks than expected and may not paginate even when product UI suggests older bookmarks exist. xc bookmarks remote and xc bookmarks local sync can only ingest what the API returns.

Posting Guidelines

Always confirm with the user before posting. Never post, like, repost, follow, block, mute, or send DMs without explicit approval. Read operations (search, timeline, user lookup, mentions, trends) are safe to run freely.

When composing posts:

• X limit is 280 characters (or 25,000 for Premium subscribers)
• Use --thread for longer content
• Delete test posts after verification: xc delete <id>

Common Patterns

# Search and summarize recent discussion about a topic
xc search "topic" -n 10 --json | jq '.[] | {text: .text, author: .author}'

# Post a thread
xc post "1/ Here's a thread about..." --thread "2/ Second point" "3/ Final thought"

# Check spending before a batch operation
xc budget show
xc cost --daily

# See who engaged with a post
xc likes <post-id>
xc reposts <post-id>
xc quotes <post-id>

# Manage your block/mute lists
xc blocked --json
xc muted --json

# Build a local bookmark archive and search it offline
xc bookmarks local sync --days 30
xc bookmarks local search "paperclip agents"
xc bookmarks local list --has-link --has-media
xc bookmarks local show https://x.com/user/status/123

# Inspect local bookmark storage directly
xc bookmarks local status
xc bookmarks local sql 'select count(*) from bookmark_posts'

Bookmark Workflow

Use this when the user wants bookmark search, bookmark archive stats, or cheap repeated access after an initial sync.

Remote vs local

• xc bookmarks remote reads live from X and costs API calls every time.
• xc bookmarks local ... reads from the local SQLite cache after sync and is effectively free after ingestion.

Recommended flow

xc bookmarks local status
xc bookmarks local sync --days 30
xc bookmarks local search "query"
xc bookmarks local show <post-id-or-url>

Local bookmark commands

xc bookmarks local sync [--days N] [--max-pages N] [--account NAME] [--json]
xc bookmarks local status [--account NAME] [--json]
xc bookmarks local list [--author QUERY] [--days N|--since RFC3339] [--before RFC3339] [--has-link] [--has-media] [-n N] [--account NAME] [--json]
xc bookmarks local search <query> [--author QUERY] [--days N|--since RFC3339] [--before RFC3339] [--has-link] [--has-media] [-n N] [--account NAME] [--json]
xc bookmarks local show <post-id-or-url> [--account NAME] [--json]
xc bookmarks local sql '<read-only sql>' [--account NAME] [--json]

What gets cached

• bookmark post text
• long-post text (note_tweet) when available
• article title/body when available
• public metrics
• links, media metadata, and some referenced/source posts

Good uses

• search bookmarks without paying for repeated API reads
• inspect article full text from already synced bookmarks
• get local stats with status or sql
• browse by author, media, or link presence

Limitations

• local cache only contains what X's official bookmark APIs return
• unbookmark removes from X but does not purge the cached local archive row
• sql is read-only by design