XActions CLI Reference

The Complete X/Twitter Automation Toolkit
Author: nich (@nichxbt). Run xactions --version for the version you have installed.

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

Most read commands need no account at all. Profiles, timelines, threads, and media all work on the guest tier the moment you install. Logging in unlocks search, followers, following, likes, bookmarks, and DMs. xactions doctor tells you which tier you are on right now.

ask

Ask how to do something with XActions and get a sourced answer plus what to run. No API key needed.

xactions ask "how do I unfollow everyone?"
xactions ask "scrape followers" --json
echo "how do I download a video" | xactions ask

The answer streams as it is written and ends with a Run it block naming the browser script, CLI command or MCP tool that does the job. Retrieval is local to the install, so it answers with no network once the free lanes are unreachable. Full guide: Ask XActions.

Table of Contents

• Installation
• Quick Start
• Finding your way around
  • xactions quickstart
  • xactions completion
  • xactions skills
• Authentication
  • xactions login
  • xactions logout
• Scraping Commands
  • xactions profile
  • xactions followers
  • xactions following
  • xactions non-followers
  • xactions tweets
  • xactions search
  • xactions hashtag
  • xactions thread
  • xactions media
  • xactions info
• Persona Commands
  • xactions persona create
  • xactions persona list
  • xactions persona run
  • xactions persona status
  • xactions persona edit
  • xactions persona delete
• Agent Commands
• Plugin Commands
• Stream Commands
• Workflow Commands
• Graph Commands
• Portability Commands
• Cross-Platform Scraping
• AI Writer Commands
• AI Content Optimizer
• Analytics Commands
• CRM Commands
• Scheduling Commands
• RSS Monitor
• Notifications
• Dataset Management
• Team Management
• Bulk Operations
• Import/Export Compatibility
• MCP Config
• Output Formats
  • Compact output for agents
• Environment Variables
• Configuration
• Troubleshooting

Installation

Install XActions globally using npm:

npm install -g xactions

Verify the installation:

xactions --version
xactions doctor      # checks Node, the browser, the MCP server, and what works right now

Requirements

• Node.js: v18.0.0 or higher
• npm: v8.0.0 or higher
• An X/Twitter account only for search, followers, following, likes, bookmarks, and DMs. Everything else works logged out.

Quick Start

npm install -g xactions

xactions quickstart          # guided first run, adapts to what you have set up
xactions doctor              # verify the install and see which tier you are on

xactions profile NASA        # works with no account
xactions tweets NASA --limit 20
xactions analyze NASA        # engagement rate, cadence, content mix, best posting hour

xactions connect             # log in once, in a real browser, to unlock the rest
xactions search "your topic" --limit 50
xactions followers yourhandle --limit 500 --output followers.json

xactions connect drives a real browser: you log in normally and the session is captured for you. xactions login now also imports cookies without DevTools, via --from-browser (reads your browser's cookie DB) or --cookies-file (an exported cookies file); with no flags it prompts you to paste auth_token and ct0.

Finding your way around

There are more than fifty commands. Running xactions with no arguments prints them grouped by task rather than alphabetically:

Start here              Set up and verify the install
Read an account         Works with no login at all
Followers and audience  Who follows whom, and who is worth your time
Search and monitor      Find posts, then keep watching them
Write and grow          Draft, sharpen, schedule, and recycle posts
Automate                Run it without you
Move data               Export, import, convert, migrate, diff
Low level               The raw HTTP client

xactions help <command> gives the full flag list for any one command.

xactions quickstart

A guided first run. Reads what you already have configured and prints the three commands that will produce a result on your machine, then the directions worth exploring next.

xactions quickstart
xactions quickstart --json    # just the detected setup state, for scripts

The JSON form reports the config directory, whether a session is saved, and which tier (guest or session) you are on.

xactions completion

Tab completion for bash, zsh, and fish. The script is generated from the live command tree, so it covers every command, sub-command, and flag, and stays correct as commands are added.

# bash
xactions completion bash > /etc/bash_completion.d/xactions
# or, without root:
echo 'source <(xactions completion bash)' >> ~/.bashrc

# zsh
xactions completion zsh > "${fpath[1]}/_xactions" && compinit
# or:
echo 'source <(xactions completion zsh)' >> ~/.zshrc

# fish
xactions completion fish > ~/.config/fish/completions/xactions.fish

Regenerate it after upgrading XActions so newly added commands complete.

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. Four ways in, fastest first.

Syntax:

xactions login [--from-browser [browser]] [--cookies-file <path>]

Options:

With no flags, xactions login prompts you to paste auth_token and ct0 by hand.

1. Read cookies from your browser (no DevTools, no copy/paste):

$ xactions login --from-browser firefox
✔ Imported 4 x.com cookies from firefox
  Saved to ~/.xactions/cookies.json (owner-only)
  auth_token + ct0 captured. Session-tier commands are unlocked.

--from-browser reads the browser's own cookie database. It works headlessly for Firefox on every platform, and for Chromium-family browsers on Linux (default keyring-less key) and macOS (via the Keychain). If a Chromium browser seals its cookies with the system keyring (GNOME Keyring / KWallet), or you are on Windows, the command prints the exact --cookies-file export path to use instead. Nothing is faked and nothing is sent anywhere.

2. Import a cookies file you exported:

$ xactions login --cookies-file ~/Downloads/x.com_cookies.txt
✔ Imported 4 x.com cookies
  Saved to ~/.xactions/cookies.json (owner-only)
  auth_token + ct0 captured. Session-tier commands are unlocked.

Accepted formats (auto-detected):

• Netscape cookies.txt — what curl, wget, and the "Get cookies.txt LOCALLY" extension write (tab-separated, #HttpOnly_ prefixes supported).
• Cookie-Editor / EditThisCookie JSON — a [{name, value, domain, ...}] array.
• Playwright / Puppeteer storageState — a { cookies: [...] } object.
• Raw header string — auth_token=...; ct0=....

Only x.com / twitter.com cookies are extracted; anything else in the export is dropped.

3. Log in through a real browser window: run xactions connect. It opens a real Chrome window, you log in normally (2FA included), and the session is captured when you finish.

4. Paste the two cookies by hand:

$ xactions login

⚡ XActions Login Setup
...
? Enter your auth_token cookie: ********
? Enter your ct0 cookie (optional, press Enter to skip): ********

✓ Authentication saved!

To find them in DevTools: open x.com logged in, press F12, go to the Application tab (Chrome) or Storage tab (Firefox), expand Cookies → https://x.com, and copy the values of auth_token and ct0.

⚠️ Security Note: Your session is stored locally in ~/.xactions/cookies.json and ~/.xactions/config.json with owner-only permissions. Never share these values 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 engage

Like, repost, and reply across a profile, a search, or a list, with replies from templates or from an LLM given a brief. Needs a logged-in session (xactions connect) for anything but --dry-run.

xactions engage [username] [options]
xactions engage --search "<query>" [options]
xactions engage --list <id> [options]

xactions engage nasa --like --repost --dry-run
xactions engage nasa --like --comment --template "Solid work on this, {name}."
xactions engage --search "open source AI" --like --comment --prompt "curious builder" --max-likes 50
xactions engage --list 1234567890 --like --keyword solana,rust --limit 25

Progress is saved per feed in ~/.xactions/engage/, so a second run skips what the first finished. Full guide, including the browser-console and MCP versions: engage.md.

xactions info

Display XActions information, version, and links.

Syntax:

xactions info

Example:

$ xactions info

⚡ XActions v3.5.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 [email protected]
   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

Apache 2.0 License - see LICENSE for details.

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

Skills

xactions skills

Install the bundled agent skills (the skills/*/SKILL.md files) where your coding agent reads them. Resolves the skills directory relative to the package, so it works from a global npm install.

xactions skills list [--json]
xactions skills show <name> [--json]
xactions skills install [names...] [--all] [--target <target>] [--global] [--json]
xactions skills uninstall [names...] [--all] [--target <target>] [--global] [--json]

xactions skills install --all --global
# Output:
#   + a2a-multi-agent                claude    installed /home/you/.claude/skills/a2a-multi-agent
#   + account-backup                 claude    installed /home/you/.claude/skills/account-backup
#   ...
#   49 installed

xactions skills install account-backup --global
#   = account-backup                 claude    unchanged /home/you/.claude/skills/account-backup

xactions skills list
#   account-backup                 claude (global)
#                                  Export and backup your X/Twitter account data ...

Names match a skill id (account-backup) or its display name, case-insensitively. Every run is idempotent; doctor counts installs per target. The full target table and what each wrapper contains are in skills.md.

Compact output for agents

--compact is a global flag for the read commands: profile, tweets, search, thread, followers, following, non-followers, hashtag, media, and analyze. It prints one record per line as tab-separated key=value pairs with only the essential fields, no colours, no spinner, no box drawing. It costs a fraction of the tokens of --json and is trivial to cut or awk.

xactions tweets nasa --limit 3 --compact
# id=2092744659667673582	username=NASA	date=2026-08-27T01:23:02.000Z	likes=2958	retweets=665	replies=89	views=467791	text=A partial lunar eclipse will pass over the Americas ...
# id=2092721435663798658	username=NASA	date=2026-08-26T23:50:45.000Z	likes=776	retweets=91	replies=30	views=376104	text=On Aug. 30, @NASARoman is scheduled to lift off ...

xactions profile nasa --compact --fields username,followers,verified
# username=NASA	followers=92350973	verified=false

xactions analyze nasa --compact
# username=NASA	followers=92350972	following=118	postsPerDay=2.78	engagementRate=0.004	medianEngagement=3890	mediaShare=100	bestWeekday=Wednesday

--fields id,text,likes picks exactly those columns, in that order. The names are the same on every command, so likes means likes whether the record came from tweets, search, or thread:

Any raw field of the underlying record can also be named in --fields (for example permanentUrl or isRetweet); a field the record lacks is skipped rather than printed empty. Newlines and tabs inside a value become single spaces so a line is always one record. Dates print as ISO 8601.

--compact outranks --output and --google-sheets, the same way --json does. When stdout is a pipe, both --json and --compact keep the spinner completely silent, so nothing lands on stderr but a real error.

Drafts (approve MCP write calls from the terminal)

When an MCP client runs with XACTIONS_MCP_REQUIRE_APPROVAL=1, every write tool call (post, reply, like, follow, DM, delete, ...) is held in ~/.xactions/mcp-drafts.json instead of running. xactions drafts is the terminal side of that queue: read exactly what the agent wanted to do, release it, or drop it. XACTIONS_HOME moves the store; the MCP server and this command read the same file.

xactions drafts list                    # newest first: id, status, age, tool, args
xactions drafts list --status pending   # pending, executed, failed, or all
xactions drafts show 3f9c1a2b           # full arguments, and the result or error once it ran
xactions drafts approve 3f9c1a2b        # run it now, exactly as submitted
xactions drafts approve --all           # every pending draft, oldest first
xactions drafts discard 3f9c1a2b        # delete without running
xactions drafts clear                   # drop executed and failed drafts, keep pending ones

  ID        STATUS    AGE       TOOL                      ARGS
  3f9c1a2b  pending   4m        x_post_tweet              text="Shipping approval mode today."
  a81d02c7  executed  2h        x_follow_user             username="nasa"

  2 drafts, 1 pending. Approve one with `xactions drafts approve <id>`, everything with `--all`.

Approval replays the call through the MCP server's own dispatcher, so an approved draft runs the same code path the live tool would have. A draft that already ran is refused, so nothing posts twice; a failed run keeps the draft with its error so you can read it with show and retry by re-creating it. Every sub-command takes --json; errors under --json come back as {"error": "..."} with exit code 1. The MCP server is only loaded by approve, so list, show, discard and clear are instant.

Archive (the X data export, without scraping)

X hands you your full history as a zip (Settings > Your account > Download an archive of your data). xactions archive reads that zip, or the folder you extracted it to, straight from disk. Nothing here needs a login or the network.

xactions archive summary twitter-2026-01-01-abc123.zip
xactions archive summary ./twitter-export --sections tweets,likes --top 5 --json
xactions archive export twitter-2026-01-01-abc123.zip --out exports/me
xactions archive export twitter-2026-01-01-abc123.zip --out exports/me --formats json,csv
xactions archive migrate twitter-2026-01-01-abc123.zip --to bluesky
xactions archive migrate twitter-2026-01-01-abc123.zip --to bluesky --execute --handle me.bsky.social --password app-pass
xactions archive migrate twitter-2026-01-01-abc123.zip --to mastodon --execute --instance https://fosstodon.org --token ...

✔ Read twitter-2026-01-01-abc123.zip (zip)

  X archive for @nichxbt (zip)
  Account created: 2019-03-01
  Tweets span:     2024-01-01 to 2025-03-16

  Tweets       5 (3 original, 1 replies, 1 retweets, 2 with media)
  Likes        2
  Following    3
  ...
  Top hashtags
    #xactions  3

A spinner tracks the scan (Scanning 4/12 data/tweets.js, Parsed tweets (18,204 records) from data/tweets.js). Under --json with stdout piped, the spinner is silent and only the document is printed, so xactions archive summary me.zip --json | jq .counts works as expected.

Doctor: query IDs and account pool

xactions doctor has two extra lines beyond the environment and session checks:

• GraphQL query IDs. X rotates the persisted query IDs of its GraphQL operations whenever it ships a new web bundle, and a stale one answers 404 Query not found. The line reports how many discovered IDs are cached in ~/.xactions/query-ids.json, how old they are, and warns past the 24 hour freshness window. xactions doctor --refresh-ids discovers the current IDs from x.com before running the checks and reports the refresh result. With no cache, the pinned table in src/scrapers/twitter/http/endpoints.js is in use, which is fine until X rotates.
• Accounts. If a multi-account pool exists (~/.xactions/accounts.db), the line reports how many accounts are configured, how many can serve right now, how many are cooling down on a rate limit (with the next reset), and how many are locked after a 401/403. With no pool it says so as a warning and moves on; doctor never creates one.

  ✓ GraphQL query IDs   142 query IDs cached, 3h old (/home/me/.xactions/query-ids.json)
  ! Accounts            No account pool at /home/me/.xactions/accounts.db; every call uses the single saved session