📚 XActions Documentation

🚀 Quick Start (60 Seconds)

Get started with XActions in under a minute. Choose your preferred method:

1. Go to x.com and log in
2. Navigate to the relevant page (e.g., /following)
3. Press F12 to open DevTools
4. Click "Console" tab
5. Paste the script and press Enter

# Install globally
npm install -g xactions

# Or use npx (no install)
npx xactions --help

npm install xactions

// In your code:
const xactions = require('xactions');
const profile = await xactions.scrapeProfile('elonmusk');

💻 CLI Installation

Requirements

• Node.js 18+ (check with node --version)
• npm or yarn package manager

Install Globally

# npm
npm install -g xactions

# yarn
yarn global add xactions

# Verify installation
xactions --version

Or Use Without Installing

# Run any command with npx
npx xactions scrape profile elonmusk
npx xactions mcp

📖 CLI Reference

📦 Node.js API

Installation

npm install xactions

Basic Usage

const xactions = require('xactions');

// Scrape a profile
const profile = await xactions.scrapeProfile('elonmusk');
console.log(profile);
// { username, name, bio, followers, following, tweets, ... }

// Scrape followers
const followers = await xactions.scrapeFollowers('elonmusk', { limit: 100 });
console.log(`Found ${followers.length} followers`);

// Scrape following
const following = await xactions.scrapeFollowing('elonmusk', { limit: 100 });

// Scrape tweets
const tweets = await xactions.scrapeTweets('elonmusk', { limit: 50 });

// Search tweets
const results = await xactions.searchTweets('web3 crypto', { limit: 100 });

Advanced Options

// Configure scraper options
const xactions = require('xactions');

// With authentication (for protected actions)
const client = xactions.createClient({
  authToken: process.env.X_AUTH_TOKEN,
  headless: true,  // Run browser in background
  timeout: 30000,  // 30 second timeout
});

// Use authenticated client
const myFollowers = await client.scrapeFollowers('myusername');
await client.close();

🤖 MCP Server Setup

Connect XActions to Claude Desktop or any MCP-compatible AI agent.

Quick Setup

# Start MCP server
npx xactions mcp

Claude Desktop Configuration

Add to your ~/.claude/config.json:

{
  "mcpServers": {
    "xactions": {
      "command": "npx",
      "args": ["xactions", "mcp"],
      "env": {
        "X_AUTH_TOKEN": "your_auth_token_here"
      }
    }
  }
}

Available MCP Tools

• scrape_profile - Get user profile information
• scrape_followers - Get user's followers
• scrape_following - Get who user follows
• scrape_tweets - Get user's tweets
• search_tweets - Search tweets by keyword
• unfollow_everyone - Mass unfollow all
• unfollow_non_followers - Unfollow non-followers
• detect_unfollowers - Find who unfollowed
• auto_like - Like posts by keyword
• download_video - Download tweet videos

🌐 Browser Scripts Guide

Browser scripts are the easiest way to use XActions. No installation required!

How to Use

1. Go to x.com and log in
2. Navigate to the relevant page
3. Press F12 (or Cmd+Option+J on Mac) to open DevTools
4. Click the Console tab
5. Paste the script and press Enter

Available Scripts

See the Features page for all scripts with full code.

• Unfollow Everyone - Mass unfollow all accounts
• Unfollow Non-Followers - Remove non-followers
• Smart Unfollow - Unfollow with logging
• Detect Unfollowers - Find who unfollowed you
• Auto Liker - Like posts by keyword
• Follow Engagers - Follow users from likes
• Leave Communities - Leave all communities
• Video Downloader - Download tweet videos

🔐 Authentication

Some features require authentication. Here's how to get your auth token:

Getting Your Auth Token

1. Go to x.com and log in
2. Open DevTools (F12)
3. Go to Application → Cookies → x.com
4. Find the auth_token cookie
5. Copy the value

Using Auth Token

# Set as environment variable
export X_AUTH_TOKEN="your_auth_token_here"

# Or pass to CLI
xactions scrape followers myuser --auth-token="your_token"

# Or in Node.js
const client = xactions.createClient({
  authToken: process.env.X_AUTH_TOKEN
});

❓ FAQ

Is XActions free?

Yes! XActions is 100% free and open source under the MIT license. No API fees, no subscriptions.

Do I need to pay for Twitter/X API?

No! XActions uses browser automation, not the official API. This means you avoid the $100+/month API fees.

Is it safe to use?

Browser scripts run entirely in your browser. The CLI uses Puppeteer to automate a real browser. Nothing is sent to third-party servers.

Can I get banned?

Any automation carries some risk. XActions includes rate limiting and human-like delays, but aggressive use may trigger spam detection. Use responsibly!

Why did my script stop?

Browser scripts stop when you navigate away. For long-running tasks, keep the tab open or use the CLI.

How do I report bugs?

Open an issue on GitHub!

💬 Support

• GitHub Issues: Report bugs & request features
• GitHub Discussions: Ask questions & share ideas
• Twitter: @nichxbt