Twitter CLI: A Terminal-First Tool for X/Twitter Without API Keys

Introduction

In an era where social media platforms frequently change their API policies and access requirements, having reliable tools that work independently of official APIs becomes increasingly valuable. Enter twitter-cli, an open-source command-line interface that provides comprehensive Twitter/X functionality directly from your terminal—without requiring official API keys.

Developed as a Python package, this tool represents a practical solution for developers, content creators, researchers, and AI agents who need programmatic access to Twitter data and functionality.

Key Features

Reading Capabilities

• Timeline Access: Fetch both "For You" and "Following" feeds with customizable filters
• Bookmark Management: List and manage saved tweets from your account
• Advanced Search: Find tweets by keyword with support for Top/Latest/Photos/Videos tabs
• Tweet Details: View individual tweets along with their complete reply threads
• User Profiles: Access user information, tweets, likes, followers, and following lists
• Twitter Articles: Fetch long-form Twitter articles and export them as Markdown
• List Timelines: Retrieve tweets from specific Twitter Lists

Writing Operations

• Post Creation: Create new tweets and replies with optional image attachments (up to 4 images)
• Quote Tweeting: Share tweets with commentary and images
• Content Management: Delete your own tweets, manage likes/retweets, and handle bookmarks
• Structured Output: All write operations support explicit JSON/YAML output for scripting

Authentication & Anti-Detection

Unlike traditional Twitter bots that rely on official API keys, twitter-cli uses a clever authentication approach:

1. Browser Cookie Extraction: Automatically extracts Twitter cookies from Arc, Chrome, Edge, Firefox, or Brave browsers
2. Environment Variables: Fallback to TWITTER_AUTH_TOKEN and TWITTER_CT0 variables
3. Anti-Detection Features:
4. TLS fingerprint impersonation using curl_cffi with dynamic Chrome version matching
5. Request timing jitter to avoid pattern detection
6. Write operation delays (1.5–4s random) to mitigate rate limits
7. x-client-transaction-id header generation
8. Proxy Support: Route requests through HTTP or SOCKS5 proxies via TWITTER_PROXY environment variable

Installation & Setup

Recommended Installation

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

# Using pipx
pipx install twitter-cli

Quick Start Examples

# Fetch home timeline (For You)
twitter feed

# Fetch Following timeline
twitter feed -t following

# Search for specific content
twitter search "Claude Code"
twitter search "AI agent" -t Latest --max 50

# View tweet details
twitter tweet 1234567890
twitter tweet https://x.com/user/status/1234567890

# Post a new tweet
twitter post "Hello from twitter-cli!"

# Post with images
twitter post "Gallery" -i a.png -i b.jpg -i c.webp

Configuration & Customization

Create a config.yaml file in your working directory to customize behavior:

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
  maxRetries: 3
  retryBaseDelay: 5.0
  maxCount: 200

The scoring system allows you to filter content based on engagement metrics, with configurable weights for different interaction types.

AI Agent Integration

One of twitter-cli's standout features is its excellent support for AI agent workflows:

Structured Output Formats

# YAML output (recommended for AI agents)
twitter feed --yaml

# JSON output
twitter feed --json

# Export to file for processing
twitter feed --output tweets.json

Skills Integration

# Install as an AI agent skill
npx skills add jackwener/twitter-cli

The tool ships with a SKILL.md file specifically designed for AI agent execution, making it easy to incorporate Twitter functionality into automated workflows.

Best Practices for Safe Usage

To avoid account restrictions or bans, follow these guidelines:

1. Use a Proxy: Set TWITTER_PROXY to avoid direct IP exposure
2. Control Request Volume: Use --max 20 instead of --max 500
3. Avoid Frequent Restarts: Each startup fetches x.com to initialize anti-detection headers
4. Use Browser Cookie Extraction: Provides full cookie fingerprint for more natural traffic patterns
5. Prefer Residential IPs: Datacenter IPs are more likely to trigger rate limiting

Troubleshooting Common Issues

Authentication Problems

• No Twitter cookies found: Ensure you're logged into x.com in a supported browser
• Cookie expired or invalid: Re-login to x.com and retry
• macOS Keychain issues: Unlock keychain or modify access controls for your terminal app

API Errors

• Twitter API error 404: Usually indicates GraphQL query ID rotation—simply retry the command
• Rate limiting: The tool includes automatic retry with exponential backoff

Windows-Specific Issues

• Pipe/subprocess output capture: This is a ConPTY issue with Windows Terminal. Use Git Bash with "windowsEnableConpty": false in terminal settings

Project Structure & Development

The codebase is well-organized and actively maintained:

twitter_cli/
├── cli.py           # Main command-line interface
├── client.py        # HTTP client with anti-detection
├── graphql.py       # GraphQL query handling
├── parser.py        # Data parsing logic
├── auth.py          # Authentication management
├── config.py        # Configuration handling
├── filter.py        # Content filtering algorithms
└── models.py        # Data models

To contribute or modify:

# Clone the repository
git clone [email protected]:jackwener/twitter-cli.git
cd twitter-cli

# Install development dependencies
uv sync --extra dev

# Run tests
uv run pytest -q

Related Tools

The developer maintains several similar CLI tools for other platforms:

• bilibili-cli: Bilibili video, user, search, and feeds
• discord-cli: Discord local-first sync, search, and export
• tg-cli: Telegram local-first sync, search, and export
• xiaohongshu-cli: Xiaohongshu (小红书) notes and account workflows

Conclusion

twitter-cli represents a sophisticated approach to Twitter automation that bypasses the limitations of official APIs while maintaining robust functionality. Its terminal-first design makes it ideal for:

• Developers who need programmatic Twitter access
• Researchers collecting social media data
• Content Creators managing multiple accounts
• AI Agents requiring structured Twitter data
• Power Users who prefer terminal workflows

With its open-source nature, active maintenance, and thoughtful design around anti-detection measures, twitter-cli offers a valuable tool for anyone needing reliable, flexible access to Twitter/X functionality without the constraints of official API programs.

Repository: https://github.com/jackwener/twitter-cli License: Apache-2.0 Stars: 2.4k+ Last Updated: April 2026