MCPInstall

twitter-cli-skill

by reason-machinesMarketing & SEO

Terminal-first Twitter/X CLI for reading feeds, bookmarks, search, and posting tweets without API keys

Installs
227
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/reason-machines/devtools-skills --skill twitter-cli-skill
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads twitter-cli-skill automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

twitter-cli

Skill by ara.so — Devtools Skills collection.

Overview

twitter-cli is a Python-based terminal CLI for Twitter/X that works without API keys. It uses browser cookie authentication to read timelines (For You, Following), bookmarks, search results, user profiles, and post/delete tweets. All commands support structured output (--json, --yaml) for AI agent pipelines.

Key capabilities:

  • Read: feed, bookmarks, search, tweet detail, article, list timeline, user lookup
  • Write: post, reply, quote, delete, like, retweet, bookmark
  • Auth: browser cookie extraction (Arc/Chrome/Edge/Firefox/Brave) or env vars
  • Anti-detection: TLS fingerprinting, full cookie forwarding, request jitter
  • Output: rich tables (default), JSON, YAML, Markdown (articles)

Installation

# Recommended: uv tool (fast, isolated)
uv tool install twitter-cli

# Alternative: pipx
pipx install twitter-cli

# Upgrade to latest
uv tool upgrade twitter-cli

From source:

git clone git@github.com:jackwener/twitter-cli.git
cd twitter-cli
uv sync

Authentication

Priority order:

  1. Environment variables: TWITTER_AUTH_TOKEN + TWITTER_CT0
  2. Browser cookies (auto-extracted from Arc/Chrome/Edge/Firefox/Brave)

Browser cookie extraction (recommended):

# Auto-detect browser and extract all Twitter cookies
twitter feed

# Specify browser explicitly
TWITTER_BROWSER=chrome twitter feed

# Chrome multi-profile
TWITTER_CHROME_PROFILE="Profile 2" twitter feed

Manual environment variables:

export TWITTER_AUTH_TOKEN="your_auth_token"
export TWITTER_CT0="your_ct0_token"
twitter feed

Proxy support:

export TWITTER_PROXY=http://127.0.0.1:7890
# or
export TWITTER_PROXY=socks5://127.0.0.1:1080

Core Commands

Read Timeline

# For You feed (default)
twitter feed

# Following feed
twitter feed -t following

# Limit results
twitter feed --max 20

# Full text (no truncation)
twitter feed --full-text

# Structured output for agents
twitter feed --json
twitter feed --yaml

# With ranking filter
twitter feed --filter --max 50

# Pagination cursor
twitter feed --cursor "DAABCgABGdE..."

Search

# Basic search
twitter search "AI agent"

# Search type: Top, Latest, Photos, Videos
twitter search "machine learning" -t Latest

# Full text + JSON output
twitter search "python" --full-text --json

# Advanced filters
twitter search "climate" --from scientist --lang en --since 2026-01-01
twitter search "news" --exclude retweets --has links

# Save to file
twitter search "trending" -o results.json

# Apply ranking filter
twitter search "tech" --filter

Bookmarks

# List bookmarks
twitter bookmarks

# Limit + full text
twitter bookmarks --max 30 --full-text

# Export as YAML
twitter bookmarks --yaml

Tweet Detail (tweet + replies)

# By tweet ID
twitter tweet 1234567890

# By URL
twitter tweet https://x.com/user/status/1234567890

# Full text in reply table
twitter tweet 1234567890 --full-text

# Structured output
twitter tweet 1234567890 --json

Show Command (open tweet by index)

# After running `twitter feed` or `twitter search`:
twitter show 2                    # Open tweet #2 from last list
twitter show 2 --full-text
twitter show 2 --json

Twitter Article (fetch and export as Markdown)

# By article ID
twitter article 1234567890

# By URL
twitter article https://x.com/user/article/1234567890

# Export as Markdown
twitter article 1234567890 --markdown
twitter article 1234567890 --output article.md

# JSON output
twitter article 1234567890 --json

List Timeline

# Fetch tweets from a Twitter List
twitter list 1539453138322673664

# Pagination
twitter list 1539453138322673664 --cursor "DAABCgABGdE..."

# Full text
twitter list 1539453138322673664 --full-text

User Lookup

# Profile
twitter user elonmusk

# User tweets
twitter user-posts elonmusk --max 20
twitter user-posts elonmusk --full-text -o tweets.json

# User likes (own account only, private since Jun 2024)
twitter likes elonmusk --max 30

# Followers
twitter followers elonmusk --max 50

# Following
twitter following elonmusk --max 50

Write Operations

Post Tweet

# Simple tweet
twitter post "Hello from twitter-cli!"

# Tweet with image (up to 4)
twitter post "Hello!" --image photo.jpg
twitter post "Gallery" -i a.png -i b.jpg -i c.webp

# Structured output
twitter post "Hello from twitter-cli!" --json

Reply

# Reply to tweet
twitter post "Nice!" --reply-to 1234567890

# Reply with image
twitter reply 1234567890 "Great!" -i screenshot.png

Quote Tweet

# Quote with text
twitter quote 1234567890 "Check this out"

# Quote with image
twitter quote 1234567890 "Look at this chart" -i chart.png

Delete Tweet

twitter delete 1234567890

Like / Unlike

twitter like 1234567890
twitter like 1234567890 --yaml
twitter unlike 1234567890

Retweet / Unretweet

twitter retweet 1234567890
twitter unretweet 1234567890

Bookmark / Unbookmark

twitter bookmark 1234567890
twitter unbookmark 1234567890

Follow / Unfollow

twitter follow elonmusk --json
twitter unfollow elonmusk

Configuration

Create config.yaml in your working directory:

fetch:
  count: 50

filter:
  mode: "topN"          # "topN" | "score" | "all"
  topN: 20
  minScore: 50
  lang: []
  excludeRetweets: false
  weights:
    likes: 1.0
    retweets: 3.0
    replies: 2.0
    bookmarks: 5.0
    views_log: 0.5

rateLimit:
  requestDelay: 2.5     # base delay (randomized ×0.7–1.5)
  maxRetries: 3
  retryBaseDelay: 5.0
  maxCount: 200

Scoring formula:

score = likes_w * likes
      + retweets_w * retweets
      + replies_w * replies
      + bookmarks_w * bookmarks
      + views_log_w * log10(max(views, 1))

Filter modes:

  • topN: Keep highest N tweets by score
  • score: Keep tweets where score >= minScore
  • all: Return all tweets sorted by score

AI Agent Usage

All commands support --json or --yaml for structured output. Non-TTY stdout defaults to YAML.

Example: Fetch and parse timeline

import subprocess
import yaml

result = subprocess.run(
    ["twitter", "feed", "--max", "10", "--yaml"],
    capture_output=True,
    text=True,
    check=True
)
data = yaml.safe_load(result.stdout)
for tweet in data["tweets"]:
    print(f"{tweet['author']['username']}: {tweet['text']}")

Example: Post tweet from Python

import subprocess
import json

result = subprocess.run(
    ["twitter", "post", "Hello from Python!", "--json"],
    capture_output=True,
    text=True,
    check=True
)
response = json.loads(result.stdout)
print(f"Tweet ID: {response['tweetId']}")

Example: Search and filter

# Get top 10 AI tweets from today as JSON
twitter search "AI agent" --since 2026-05-17 --filter --max 10 --json

Structured output contract: See SCHEMA.md

Common Patterns

Export bookmarks to file

twitter bookmarks --max 100 --json > bookmarks.json

Monitor user tweets

# Fetch latest 5 tweets from user
twitter user-posts elonmusk --max 5 --yaml

Search and rank by engagement

# Top 10 tweets about "AI" by score
twitter search "AI" --filter --max 10 --full-text

Post with multiple images

twitter post "My photo gallery" -i img1.jpg -i img2.png -i img3.webp

Reply to tweet with image

twitter reply 1234567890 "Here's the screenshot" -i screenshot.png

Extract article as Markdown

twitter article 1234567890 --markdown --output ~/articles/ai-safety.md

Use proxy for all requests

export TWITTER_PROXY=http://127.0.0.1:7890
twitter feed --max 20

Troubleshooting

No Twitter cookies found

Solution:

  1. Log in to x.com in a supported browser (Arc/Chrome/Edge/Firefox/Brave)
  2. Or set TWITTER_AUTH_TOKEN and TWITTER_CT0 manually
  3. Run with -v for diagnostics: 
    twitter -v feed

Cookie expired (HTTP 401/403)

Solution: Re-login to x.com and retry.

Keychain access denied (macOS)

SSH sessions:

security unlock-keychain ~/Library/Keychains/login.keychain-db

Local terminal:

  • Open Keychain Access → search for "<Browser> Safe Storage"
  • Access Control → add Terminal app → Save Changes
  • Or click "Always Allow" when prompted

Twitter API error 404

Solution: Retry command. The client attempts a live queryId fallback when GraphQL IDs rotate.

Invalid tweet JSON file

Solution: Regenerate using:

twitter feed --json > tweets.json

Windows: no pipe output in AI agent subprocess

Issue: ConPTY intercepts pipe output from network commands.

Fix:

  1. Use Git Bash as terminal shell
  2. Set "windowsEnableConpty": false in terminal settings
  3. Standard subprocess.run(capture_output=True) works correctly

Rate limiting (HTTP 429)

Solution:

  • Use --max to limit requests
  • Set TWITTER_PROXY to avoid direct IP exposure
  • Increase rateLimit.requestDelay in config.yaml
  • Use residential proxies instead of datacenter IPs

Best Practices

  1. Use a proxy — set TWITTER_PROXY to avoid direct IP exposure
  2. Keep request volumes low — prefer --max 20 over --max 500
  3. Don't run too frequently — each startup fetches x.com to initialize headers
  4. Use browser cookie extraction — provides full cookie fingerprint
  5. Avoid datacenter IPs — residential proxies are safer
  6. Upgrade regularly — uv tool upgrade twitter-cli to avoid outdated API handling

Output Modes

  • Rich table (default): Interactive reading in terminal
  • --full-text: Show full tweet text in tables
  • --yaml: Structured output for agents (default for non-TTY)
  • --json: Strict JSON for parsers
  • -c / --compact: Token-efficient compact output
  • -o FILE: Save to file

Development

# Install dev dependencies
uv sync --extra dev

# Lint
uv run ruff check .

# Tests
uv run pytest -q

Project Structure

twitter_cli/
├── cli.py           # Command-line interface
├── client.py        # HTTP client + anti-detection
├── graphql.py       # GraphQL query IDs, URL building
├── parser.py        # Tweet/User/Media parsing
├── auth.py          # Cookie extraction
├── config.py        # Configuration loading
├── filter.py        # Ranking/scoring logic
├── formatter.py     # Rich table formatting
├── output.py        # JSON/YAML serialization
└── models.py        # Data models (Tweet, User, Media)

Example Workflows

Daily AI news digest

# Search AI tweets from today, rank by engagement, export as JSON
twitter search "AI" --since 2026-05-17 --filter --max 20 --json > ai_digest.json

Bookmark analysis

import subprocess
import yaml
from collections import Counter

result = subprocess.run(
    ["twitter", "bookmarks", "--max", "200", "--yaml"],
    capture_output=True, text=True, check=True
)
data = yaml.safe_load(result.stdout)

# Extract hashtags
hashtags = []
for tweet in data["tweets"]:
    hashtags.extend([h["text"] for h in tweet.get("hashtags", [])])

print(Counter(hashtags).most_common(10))

Post with automated image

import subprocess

# Generate chart, then post with image
subprocess.run(["python", "generate_chart.py"], check=True)
subprocess.run([
    "twitter", "post",
    "Daily metrics update",
    "-i", "chart.png",
    "--json"
], check=True)

Monitor user and alert on keyword

#!/bin/bash
# Cron job: check user tweets for keyword
tweets=$(twitter user-posts elonmusk --max 5 --yaml)
if echo "$tweets" | grep -q "Mars"; then
  echo "Alert: New Mars tweet from @elonmusk"
fi

Related Projects

License: Apache-2.0
Repository: https://github.com/jackwener/twitter-cli
PyPI: https://pypi.org/project/twitter-cli/

FAQ

What does the twitter-cli-skill skill do?

Terminal-first Twitter/X CLI for reading feeds, bookmarks, search, and posting tweets without API keys

How do I install twitter-cli-skill?

Run npx skills add https://github.com/reason-machines/devtools-skills --skill twitter-cli-skill in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/twitter-cli-skill/ (personal) or .claude/skills/twitter-cli-skill/ (project).

Which AI agents can use twitter-cli-skill?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is twitter-cli-skill safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains twitter-cli-skill?

It is published by reason-machines in reason-machines/devtools-skills. It has 227 recorded installs.

More from reason-machines/devtools-skills

View all →

cc-switch-cli

reason-machines/devtools-skills

Cross-platform CLI tool for managing Claude Code, Codex, Gemini, OpenCode & OpenClaw providers, MCP servers, prompts, skills, and proxies.

AI & Agents316 installs

wx-cli-wechat-local-data

reason-machines/devtools-skills

Open the skill to read its SKILL.md instructions.

284 installs

chrome-devtools-mcp-automation

reason-machines/devtools-skills

Open the skill to read its SKILL.md instructions.

AI & Agents263 installs

officecli-office-automation

reason-machines/devtools-skills

Open the skill to read its SKILL.md instructions.

Productivity & Automation260 installs

autocli-web-scraping

reason-machines/devtools-skills

Open the skill to read its SKILL.md instructions.

Productivity & Automation257 installs

cli-anything-agent-native-software

reason-machines/devtools-skills

Open the skill to read its SKILL.md instructions.

257 installs

Popular marketing & seo skills

View category →

reddit-automation

flowkit-labs/skills

Find Reddit threads where people are genuinely asking for what you offer, then draft short, genuinely helpful replies — disclosing your affiliation honestly and naming your product only when it truly answers the question. Two moves: discovery — scan the right subreddits for real needs (recommendation asks, expressed pain, competitor mentions) and rank the few threads where you can actually help; drafting — write from real experience, respect each community's self-promo rules, and keep a human in the loop to review and post. This markets on Reddit the honest way: contribute value, disclose who you are, never astroturf. Distilled from the playbook behind doany.ai's Reddit agent. Triggers on "find reddit opportunities", "reddit marketing", "reddit automation", "reply on reddit for my product", "reddit community engagement", "reddit lead gen", or any ask to turn Reddit threads into genuine, disclosed marketing replies.

Marketing & SEO1.1M installs

twitter-automation

101-skills/superpowers

Automate Twitter/X with posting, engagement, and user management via inference.sh CLI. Apps: x/post-tweet, x/post-create (with media), x/post-like, x/post-retweet, x/dm-send, x/user-follow. Capabilities: post tweets, schedule content, like posts, retweet, send DMs, follow users, get profiles. Use for: social media automation, content scheduling, engagement bots, audience growth, X API. Triggers: twitter api, x api, tweet automation, post to twitter, twitter bot, social media automation, x automation, tweet scheduler, twitter integration, post tweet, twitter post, x post, send tweet

Marketing & SEO880K installs

twitter-automation

magentosh/superpowers

Automate Twitter/X with posting, engagement, and user management via inference.sh CLI. Apps: x/post-tweet, x/post-create (with media), x/post-like, x/post-retweet, x/dm-send, x/user-follow. Capabilities: post tweets, schedule content, like posts, retweet, send DMs, follow users, get profiles. Use for: social media automation, content scheduling, engagement bots, audience growth, X API. Triggers: twitter api, x api, tweet automation, post to twitter, twitter bot, social media automation, x automation, tweet scheduler, twitter integration, post tweet, twitter post, x post, send tweet

Marketing & SEO771.7K installs

twitter-automation

qu-skills/superpowers

Automate Twitter/X with posting, engagement, and user management via inference.sh CLI. Apps: x/post-tweet, x/post-create (with media), x/post-like, x/post-retweet, x/dm-send, x/user-follow. Capabilities: post tweets, schedule content, like posts, retweet, send DMs, follow users, get profiles. Use for: social media automation, content scheduling, engagement bots, audience growth, X API. Triggers: twitter api, x api, tweet automation, post to twitter, twitter bot, social media automation, x automation, tweet scheduler, twitter integration, post tweet, twitter post, x post, send tweet

Marketing & SEO564.3K installs

product-launch-video

heygen-com/hyperframes

Turn a product or marketing URL, pasted script, or brief into a product launch / promo video — SaaS promos, feature reveals, product demos, app and company launches. Use when the user wants to market, launch, promote, or reveal a product; the default for any commercial URL. Site tours / showcases of a website route here too — the brief carries the show-it-as-is intent. Unclear → /hyperframes.

Marketing & SEO538.7K installs

twitter-automation

skills-shell/superpowers

Automate Twitter/X with posting, engagement, and user management via inference.sh CLI. Apps: x/post-tweet, x/post-create (with media), x/post-like, x/post-retweet, x/dm-send, x/user-follow. Capabilities: post tweets, schedule content, like posts, retweet, send DMs, follow users, get profiles. Use for: social media automation, content scheduling, engagement bots, audience growth, X API. Triggers: twitter api, x api, tweet automation, post to twitter, twitter bot, social media automation, x automation, tweet scheduler, twitter integration, post tweet, twitter post, x post, send tweet

Marketing & SEO453.7K installs