XActions CLI Reference

The Complete X/Twitter Automation Toolkit
Version 3.0.0 | Author: nich (@nichxbt)

The XActions CLI provides powerful command-line tools for X/Twitter automation, scraping, and data extraction. No Twitter API required — saves you $100-$5,000+/month in API costs.

Installation

Install XActions globally using npm:

npm install -g xactions

Verify the installation:

xactions --version
# Output: 3.0.0

xactions --help

Requirements

• Node.js: v18.0.0 or higher
• npm: v8.0.0 or higher
• A valid X/Twitter account for authentication

Quick Start

# 1. Install XActions
npm install -g xactions

# 2. Authenticate with your X account
xactions login

# 3. Scrape a profile
xactions profile elonmusk

# 4. Get followers and save to file
xactions followers elonmusk --limit 500 --output followers.json

Authentication

XActions uses your X/Twitter session cookie for authentication. This approach bypasses API rate limits and doesn't require expensive API access.

xactions login

Set up authentication with your X/Twitter session cookie.

Syntax:

xactions login

Usage:

$ xactions login

⚡ XActions Login Setup

To get your auth_token cookie:
1. Go to x.com and log in
2. Open DevTools (F12) → Application → Cookies
3. Find "auth_token" and copy its value

? Enter your auth_token cookie: ********

✓ Authentication saved!

How to get your auth_token:

1. Open x.com in your browser and log in
2. Press F12 to open Developer Tools
3. Go to Application tab (Chrome) or Storage tab (Firefox)
4. Expand Cookies → click on https://x.com
5. Find the cookie named auth_token
6. Copy the Value (a long hexadecimal string)
7. Paste it when prompted by xactions login

⚠️ Security Note: Your auth_token is stored locally in ~/.xactions/config.json. Never share this token with anyone.

xactions logout

Remove saved authentication credentials.

Syntax:

xactions logout

Example:

$ xactions logout
✓ Logged out successfully

Commands

xactions profile

Fetch detailed profile information for any X/Twitter user.

Syntax:

xactions profile <username> [options]

Arguments:

Options:

Examples:

# Get profile with formatted output
xactions profile elonmusk

# Output:
# ⚡ @elonmusk
#
#   Name:      Elon Musk
#   Bio:       Mars & Cars, Chips & Dips
#   Location:  𝕏
#   Website:   x.com
#   Joined:    June 2009
#   Following: 800  Followers: 195.2M
#   ✓ Verified

# Get profile as JSON
xactions profile elonmusk --json

# Output:
# {
#   "username": "elonmusk",
#   "name": "Elon Musk",
#   "bio": "Mars & Cars, Chips & Dips",
#   "location": "𝕏",
#   "website": "x.com",
#   "joined": "June 2009",
#   "following": 800,
#   "followers": 195200000,
#   "verified": true
# }

xactions followers

Scrape the followers list for any user.

Syntax:

xactions followers <username> [options]

Arguments:

Options:

Examples:

# Scrape 100 followers (default)
xactions followers nichxbt

# Scrape 500 followers and save to JSON
xactions followers nichxbt --limit 500 --output followers.json

# Scrape 1000 followers and save to CSV
xactions followers nichxbt -l 1000 -o followers.csv

# Pipe output to jq for processing
xactions followers nichxbt --limit 50 | jq '.[].username'

Output Schema (JSON):

[
  {
    "username": "user1",
    "name": "User One",
    "bio": "Developer & Creator",
    "followers": 1500,
    "following": 200,
    "verified": false,
    "followsBack": true
  }
]

xactions following

Scrape the accounts a user is following.

Syntax:

xactions following <username> [options]

Arguments:

Options:

Examples:

# Scrape following list
xactions following nichxbt

# Scrape 200 accounts and save to JSON
xactions following nichxbt --limit 200 --output following.json

# Get following as CSV for spreadsheet analysis
xactions following nichxbt -l 500 -o following.csv

xactions non-followers

Analyze follow relationships to find accounts that don't follow you back.

Syntax:

xactions non-followers <username> [options]

Arguments:

Options:

Examples:

# Analyze your follow relationships
xactions non-followers nichxbt

# Output:
# 📊 Follow Analysis
#
#   Total Following: 450
#   Mutuals:         320
#   Non-Followers:   130
#
# Non-followers:
#   @user1 - John Doe
#   @user2 - Jane Smith
#   @user3 - Bob Wilson
#   ... and 127 more

# Save full list of non-followers to file
xactions non-followers nichxbt --limit 1000 --output non-followers.json

# Analyze and export for batch unfollowing
xactions non-followers myaccount -l 2000 -o cleanup-list.json

xactions tweets

Scrape tweets from a user's timeline.

Syntax:

xactions tweets <username> [options]

Arguments:

Options:

Examples:

# Scrape recent tweets
xactions tweets elonmusk

# Scrape 200 tweets including replies
xactions tweets elonmusk --limit 200 --replies

# Save tweets to JSON file
xactions tweets elonmusk -l 100 -o elon-tweets.json

# Export to CSV for spreadsheet analysis
xactions tweets nichxbt --limit 500 --output tweets.csv

Output Schema (JSON):

[
  {
    "id": "1234567890123456789",
    "text": "Just shipped a new feature! 🚀",
    "timestamp": "2025-12-15T10:30:00.000Z",
    "likes": 1500,
    "retweets": 200,
    "replies": 50,
    "views": 50000,
    "isReply": false,
    "isRetweet": false
  }
]

xactions search

Search for tweets matching a query.

Syntax:

xactions search <query> [options]

Arguments:

Options:

Examples:

# Search for tweets about Bitcoin
xactions search "bitcoin"

# Search with filter for top tweets
xactions search "AI agents" --filter top --limit 100

# Search for photos only
xactions search "sunset photography" -f photos -l 50 -o photos.json

# Search for people/accounts
xactions search "web3 developer" --filter people

# Complex query with quotes
xactions search '"machine learning" from:openai' --limit 200

# Save search results
xactions search "typescript tips" -o ts-tips.json

Search Operators:

xactions hashtag

Scrape tweets containing a specific hashtag.

Syntax:

xactions hashtag <tag> [options]

Arguments:

Options:

Examples:

# Scrape tweets with #buildinpublic
xactions hashtag buildinpublic

# With the # symbol (both work)
xactions hashtag "#100DaysOfCode"

# Scrape 200 tweets and save
xactions hashtag AI --limit 200 --output ai-tweets.json

# Track trending hashtag
xactions hashtag trending -l 500 -o trending.json

xactions thread

Scrape an entire tweet thread/conversation.

Syntax:

xactions thread <url> [options]

Arguments:

Options:

Examples:

# Scrape a thread (formatted output)
xactions thread https://x.com/nichxbt/status/1234567890123456789

# Output:
# 🧵 Thread:
#
# 1. First tweet in the thread explaining the concept...
#    Dec 15, 2025
#
# 2. Continuing with more details about implementation...
#    Dec 15, 2025
#
# 3. Final thoughts and call to action...
#    Dec 15, 2025

# Save thread to file
xactions thread https://x.com/user/status/123456789 -o thread.json

xactions media

Scrape media (images, videos, GIFs) from a user's timeline.

Syntax:

xactions media <username> [options]

Arguments:

Options:

Examples:

# Scrape media from a user
xactions media nichxbt

# Scrape 100 media items
xactions media photographer --limit 100 --output media.json

# Short form
xactions media artist -l 200 -o artist-media.json

Output Schema (JSON):

[
  {
    "type": "image",
    "url": "https://pbs.twimg.com/media/...",
    "tweetId": "1234567890123456789",
    "tweetUrl": "https://x.com/user/status/1234567890123456789",
    "timestamp": "2025-12-15T10:30:00.000Z",
    "alt": "Image description"
  }
]

xactions info

Display XActions information, version, and links.

Syntax:

xactions info

Example:

$ xactions info

⚡ XActions v3.0.0

The Complete X/Twitter Automation Toolkit

Features:
  • Scrape profiles, followers, following, tweets
  • Search tweets and hashtags
  • Extract threads, media, and more
  • Export to JSON or CSV
  • No Twitter API required (saves $100-$5000+/mo)

Author:
  nich (@nichxbt) - https://github.com/nirholas

Links:
  Website:  https://xactions.app
  GitHub:   https://github.com/nirholas/xactions
  Docs:     https://xactions.app/docs

Run "xactions --help" for all commands

Output Formats

XActions supports two output formats: JSON and CSV.

JSON Output

JSON is the default format when using --output with a .json extension.

# Save as JSON
xactions followers nichxbt -o followers.json

Features:

• Preserves all data types (numbers, booleans, nested objects)
• Easy to process with jq, Node.js, Python, etc.
• Suitable for programmatic use

CSV Output

Use .csv extension to export as comma-separated values.

# Save as CSV
xactions followers nichxbt -o followers.csv

Features:

• Opens directly in Excel, Google Sheets, Numbers
• Great for data analysis and reporting
• Flattens nested data structures

Stdout Output

Without --output, data is printed to stdout as JSON.

# Print to terminal
xactions followers nichxbt

# Pipe to jq for processing
xactions followers nichxbt | jq '.[].username'

# Pipe to file
xactions followers nichxbt > followers.json

# Pipe to another command
xactions followers nichxbt | wc -l

Environment Variables

XActions supports the following environment variables:

Examples

# Use auth token from environment
export XACTIONS_AUTH_TOKEN="your_auth_token_here"
xactions followers nichxbt

# Use a proxy
export XACTIONS_PROXY="http://proxy.example.com:8080"
xactions profile elonmusk

# Enable debug mode
DEBUG=xactions:* xactions followers nichxbt

# Custom config directory
XACTIONS_CONFIG_DIR=/custom/path xactions login

# Inline environment variables
XACTIONS_HEADLESS=false xactions profile nichxbt

Configuration

XActions stores configuration in ~/.xactions/config.json.

Config File Location

~/.xactions/
├── config.json      # Authentication and settings
└── cache/           # Temporary cache (optional)

Config File Structure

{
  "authToken": "your_auth_token_here",
  "headless": true,
  "timeout": 30000,
  "proxy": null
}

Manual Configuration

You can manually edit the config file:

# View current config
cat ~/.xactions/config.json

# Edit config
nano ~/.xactions/config.json

Troubleshooting

Common Issues

1. "Authentication required" error

# Solution: Run login command
xactions login

2. "Timeout" errors

# Increase timeout
XACTIONS_TIMEOUT=60000 xactions followers nichxbt

3. "Browser not found" error

XActions requires Chromium/Chrome. Install it:

# macOS
brew install --cask chromium

# Ubuntu/Debian
sudo apt install chromium-browser

# Or use Puppeteer's bundled Chromium
npm install puppeteer

4. Rate limiting

If you're being rate limited:

• Reduce the --limit value
• Add delays between commands
• Consider using a proxy

5. "Page not loading" issues

# Run with visible browser for debugging
XACTIONS_HEADLESS=false xactions profile nichxbt

Debug Mode

Enable verbose logging for troubleshooting:

DEBUG=xactions:* xactions followers nichxbt

Getting Help

• Documentation: https://xactions.app/docs
• GitHub Issues: https://github.com/nirholas/xactions/issues
• Twitter/X: @nichxbt

Command Reference Summary

License

MIT License - see LICENSE for details.

⚡ XActions
Built by nich (@nichxbt)
https://xactions.app