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

xactions persona create

Interactively create a new persona for the algorithm builder. Guides you through choosing a niche preset, engagement strategy, and activity pattern.

Syntax:

xactions persona create [options]

Options:

Available Presets:

Available Strategies:

Available Activity Patterns:

Examples:

# Interactive creation
$ xactions persona create

# One-liner
$ xactions persona create --name "CryptoBot" --preset crypto-degen --strategy aggressive --activity night-owl

# Custom niche (interactive prompts for topics, search terms, etc.)
$ xactions persona create --preset custom

xactions persona list

List all saved personas with their stats and last activity.

Syntax:

xactions persona list

Example:

$ xactions persona list

🤖 Saved Personas

  ● CryptoBot (persona_1234567890)
    Preset: crypto-degen | Strategy: aggressive
    Sessions: 42 | Follows: 320 | Likes: 1200 | Comments: 180
    Last active: 1/15/2025, 3:42:00 AM

  ○ AIResearcher (persona_0987654321)
    Preset: ai-researcher | Strategy: thoughtleader
    Sessions: 0 | Follows: 0 | Likes: 0 | Comments: 0

xactions persona run

Start the 24/7 algorithm builder for a persona. Launches a Puppeteer browser, logs in, and runs automated sessions with sleep cycles.

Syntax:

xactions persona run <personaId> [options]

Arguments:

Options:

Environment Variables:

Examples:

# Start with saved auth
$ xactions persona run persona_1234567890

# With visible browser for debugging
$ xactions persona run persona_1234567890 --no-headless

# Dry run — preview without executing
$ xactions persona run persona_1234567890 --dry-run

# Run 5 sessions then stop
$ xactions persona run persona_1234567890 --sessions 5

# Explicit auth token
$ xactions persona run persona_1234567890 --token "abc123hex..."

xactions persona status

Display detailed status, config, and lifetime stats for a persona.

Syntax:

xactions persona status <personaId>

Example:

$ xactions persona status persona_1234567890

🤖 CryptoBot — Status Report

Identity
  ID: persona_1234567890
  Preset: crypto-degen
  Created: 1/10/2025, 9:00:00 AM

Niche
  Topics: crypto, defi, web3, bitcoin, ethereum, solana, memecoins
  Search terms: 7
  Target accounts: 0xCygaar, blaboratory, DefiIgnas

Strategy
  Growth: aggressive
  Activity: night-owl
  Daily limits: 80 follows, 150 likes, 40 comments

Lifetime Stats
  Sessions: 42
  Follows: 320
  Likes: 1200
  Comments: 180
  Posts: 24
  Searches: 89
  Last active: 1/15/2025, 3:42:00 AM

Follow Graph
  Users followed: 280
  Current followers: 145
  Target: 10,000

xactions persona edit

Modify an existing persona's config without recreating it.

Syntax:

xactions persona edit <personaId> [options]

Options:

Examples:

# Change topics
$ xactions persona edit persona_123 --topics "ai,llm,agents,agi"

# Switch to conservative strategy
$ xactions persona edit persona_123 --strategy conservative

# Update target accounts
$ xactions persona edit persona_123 --target-accounts "elonmusk,sama,karpathy"

xactions persona delete

Permanently delete a saved persona and all its data.

Syntax:

xactions persona delete <personaId>

Example:

$ xactions persona delete persona_1234567890
? Delete persona persona_1234567890? This cannot be undone. (y/N) y
✅ Persona persona_1234567890 deleted

Agent Commands

xactions agent setup

Interactive 8-step setup wizard for first-time agent configuration.

xactions agent setup

Walks through niche selection, persona creation, LLM provider setup, timezone, intensity level, browser login, test run, and saves config to data/agent-config.json.

xactions agent start

Start the autonomous thought leader agent.

xactions agent start [options]

Example:

xactions agent start --config data/agent-config.json

xactions agent test

Run the agent for 5 minutes in test mode.

xactions agent test [options]

xactions agent login

Open a visible browser for manual X.com login. Saves session cookies for headless runs.

xactions agent login

xactions agent status

Show current agent status and today's action counts.

xactions agent status [options]

Example output:

📊 Agent Status — Today
  Likes:      47 / 150
  Follows:    12 / 80
  Comments:   8  / 25
  Posts:       2  / 5
  LLM cost:   $0.34

xactions agent report

Generate a growth report for the last N days.

xactions agent report [options]

Plugin Commands

xactions plugin install

Install a plugin from npm or a local path.

xactions plugin install <name>

Example:

$ xactions plugin install xactions-plugin-sentiment
✅ Installed xactions-plugin-sentiment@1.2.0
   Tools: 3 | Scrapers: 1 | Routes: 2 | Actions: 1

xactions plugin remove

Remove an installed plugin.

xactions plugin remove <name>

xactions plugin list

List all installed plugins with status.

$ xactions plugin list
 ✅ xactions-plugin-sentiment  v1.2.0  Sentiment analysis tools
 ⏸  xactions-plugin-analytics  v0.9.1  Advanced analytics (disabled)

xactions plugin enable / disable

Enable or disable a plugin without removing it.

xactions plugin enable <name>
xactions plugin disable <name>

xactions plugin discover

Scan node_modules for xactions-plugin-* packages.

xactions plugin discover

Stream Commands

xactions stream start

Start a real-time stream for an account.

xactions stream start <type> <username> [options]

Types: tweet, follower, mention

Example:

$ xactions stream start tweet nichxbt -i 30
🔴 Stream started: stream_abc123
   Type: tweet | User: nichxbt | Interval: 30s

xactions stream stop

Stop an active stream.

xactions stream stop <streamId>

xactions stream list

List all active streams and browser pool status.

$ xactions stream list
Active Streams:
  stream_abc123  tweet     nichxbt   ✅ running  polls:142  errors:0
  stream_def456  follower  nichxbt   ⏸  paused   polls:89   errors:1

Browser Pool: 2/5 active

xactions stream history

Show recent events for a stream.

xactions stream history <streamId> [options]

xactions stream pause / resume

Pause or resume a stream without losing state.

xactions stream pause <streamId>
xactions stream resume <streamId>

xactions stream status

Get detailed status of a specific stream.

xactions stream status <streamId>

xactions stream stop-all

Stop all active streams.

xactions stream stop-all

Workflow Commands

xactions workflow create

Create a workflow from a JSON file or interactively.

xactions workflow create [options]

Interactive mode prompts for: name, description, trigger type (manual/schedule/webhook), cron expression.

xactions workflow run

Run a workflow by name or ID.

xactions workflow run <name> [options]

xactions workflow list

List all saved workflows.

$ xactions workflow list
 ✅ morning-engage  wf_001  schedule (0 9 * * *)  5 steps  Morning engagement routine
 ✅ weekly-report   wf_002  manual                 3 steps  Generate weekly analytics

xactions workflow delete

Delete a workflow.

xactions workflow delete <id>

xactions workflow actions

List all available workflow actions grouped by category.

xactions workflow actions

xactions workflow runs

Show execution history for a workflow.

xactions workflow runs <workflowId> [options]

Graph Commands

xactions graph build

Build a social graph by crawling an account's network.

xactions graph build <username> [options]

Example:

$ xactions graph build nichxbt -d 2 -n 200
🕸️ Building graph for nichxbt...
   Depth: 2 | Max nodes: 200
   ████████████████████ 100%
✅ Graph saved: graph_abc123 (187 nodes, 2,341 edges)

xactions graph analyze

Run cluster, influence, and bridge analysis on a graph.

xactions graph analyze <graphId>

Output: Clusters, top influencers, bridge accounts, orbit analysis.

xactions graph recommend

Get follow/engage/unfollow recommendations from a graph.

xactions graph recommend <graphId>

Output: Suggested follows, engagement targets, watch list, safe-to-unfollow.

xactions graph export

Export a graph for visualization.

xactions graph export <graphId> [options]

xactions graph list

List all saved graphs.

xactions graph list

xactions graph delete

Delete a saved graph.

xactions graph delete <graphId>

Portability Commands

xactions export

Export a full Twitter account (profile, tweets, followers, following, bookmarks).

xactions export <username> [options]

Example:

xactions export nichxbt -f json,csv --only profile,tweets -l 1000

xactions migrate

Migrate Twitter data to Bluesky or Mastodon.

xactions migrate <username> [options]

xactions diff

Compare two account exports and show changes.

xactions diff <dirA> <dirB> [options]

Output: Follower/following deltas, tweet count changes, engagement trends, profile diffs.

Cross-Platform Scraping

xactions scrape

Multi-platform scraping for Twitter, Bluesky, Mastodon, and Threads.

xactions scrape <action> [target] [options]

Actions: profile, followers, following, tweets, search, hashtag, trending

Examples:

xactions scrape profile -p bluesky -u nichxbt.bsky.social
xactions scrape followers -p mastodon -u user -i https://mastodon.social -l 500
xactions scrape trending -p twitter

xactions platforms

List supported social media platforms.

xactions platforms

AI Writer Commands

xactions ai analyze

Analyze a user's writing voice from their tweets.

xactions ai analyze <username> [options]

xactions ai generate

Generate tweets or threads in a user's voice.

xactions ai generate <topic> [options]

xactions ai rewrite

Rewrite a tweet in a user's voice with a goal.

xactions ai rewrite <text> [options]

xactions ai calendar

Generate a weekly content calendar.

xactions ai calendar <username> [options]

AI Content Optimizer

xactions optimize

AI-optimize a tweet for engagement.

xactions optimize <text> [options]

xactions hashtags

Suggest hashtags for tweet text.

xactions hashtags <text> [options]

xactions predict

Predict tweet performance (score, reach, strengths, weaknesses).

xactions predict <text>

xactions variations

Generate tweet variations.

xactions variations <text> [options]

Analytics Commands

xactions sentiment

Analyze sentiment of text or tweet content.

xactions sentiment <text> [options]

xactions monitor

Start monitoring sentiment for a username or keyword.

xactions monitor <target> [options]

xactions report

Generate a reputation report for a monitored username.

xactions report <username> [options]

xactions history

View account history over time.

xactions history <username> [options]

xactions snapshot

Start auto-snapshotting an account (long-running).

xactions snapshot <username> [options]

xactions audience

Analyze follower overlap between two accounts.

xactions audience <username1> <username2> [options]

xactions evergreen

Find and recycle top-performing evergreen content.

xactions evergreen <username> [options]

CRM Commands

xactions crm sync

Sync followers to the built-in CRM.

xactions crm sync <username>

xactions crm tag

Tag a contact.

xactions crm tag <username> <tag>

xactions crm search

Search contacts by query.

xactions crm search <query>

xactions crm score

Auto-score all contacts based on engagement.

xactions crm score

xactions crm segment

Get members of a segment.

xactions crm segment <name>

Scheduling Commands

xactions schedule add

Add a scheduled job.

xactions schedule add <name> <cron> [options]

Example:

xactions schedule add morning-scrape "0 9 * * *" -c "xactions followers nichxbt -l 100 -o daily.json"

xactions schedule list

List all scheduled jobs.

$ xactions schedule list
 ✅ morning-scrape  0 9 * * *   Next: 2025-01-20 09:00
 ⏸  weekly-export   0 0 * * 1   Next: 2025-01-27 00:00 (disabled)

xactions schedule remove

Remove a scheduled job.

xactions schedule remove <name>

xactions schedule run

Run a job immediately (ignoring cron schedule).

xactions schedule run <name>

RSS Monitor

xactions rss add

Add an RSS feed for monitoring and auto-drafting.

xactions rss add <name> <url> [options]

Example:

xactions rss add techcrunch https://techcrunch.com/feed/ -t "🔗 {title}\n{description}\n\n{link}"

xactions rss list

List all monitored feeds.

xactions rss list

xactions rss check

Check feeds for new items and create draft posts.

xactions rss check [name]    # Check specific feed or all feeds

xactions rss drafts

View draft posts generated from RSS items.

xactions rss drafts

Notification Commands

xactions notify test

Send a test notification to a specific channel.

xactions notify test <channel>    # slack, discord, telegram, email

xactions notify send

Send a notification to all configured channels.

xactions notify send <message> [options]

xactions notify configure

Interactive configuration for notification channels (Slack, Discord, Telegram, email).

xactions notify configure

Dataset Management

xactions dataset list

List all stored scraping datasets.

xactions dataset list

xactions dataset export

Export a dataset to file.

xactions dataset export <name> [options]

xactions dataset delete

Delete a stored dataset.

xactions dataset delete <name>

Team Management

xactions team create

Create a new team.

xactions team create <name> [options]

xactions team invite

Invite a user to a team.

xactions team invite <teamId> <email> [options]

xactions team members

List team members.

xactions team members <teamId>

xactions team activity

View team activity log.

xactions team activity <teamId> [options]

Bulk Operations

Run actions in bulk from a CSV, JSON, or TXT file.

xactions bulk <action> <file> [options]

Actions: follow, unfollow, block, mute, scrape

Example:

xactions bulk follow targets.csv --delay 3000
xactions bulk scrape usernames.txt -o results.json

Import/Export Compatibility

xactions import

Import data from Apify, Phantombuster, or CSV.

xactions import <file> [options]

xactions export-data

Export data in external tool format.

xactions export-data <file> [options]

xactions convert

Convert between data formats.

xactions convert <file> [options]

MCP Config

Generate MCP server configuration for AI tools.

xactions mcp-config [options]

Example:

# Generate config for Claude Desktop
xactions mcp-config -c claude

# Write directly to Claude config file
xactions mcp-config -c claude --write

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
├── personas/        # Saved persona configurations
│   ├── persona_123.json
│   └── persona_456.json
└── 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