This guide will walk you through authenticating and running your first twitter-cli command.
Prerequisites Before you begin, make sure you have:
Installed twitter-cli (see Installation )
A Twitter/X account
Logged into x.com in one of these browsers: Chrome, Firefox, Edge, or Brave
Authentication Setup twitter-cli uses browser cookies for authentication. There are two methods:
This is the recommended method as it provides the most authentic browser fingerprint.
Log into x.com
Open your browser and log into x.com . Make sure you’re fully logged in and can see your timeline.
Verify Cookie Extraction
twitter-cli will automatically extract cookies from your browser when you run any command. No manual configuration needed! Supported Browsers : Chrome, Firefox, Edge, and Brave
Run Your First Command
Try fetching your home timeline: You should see: 🔐 Getting Twitter cookies... 📡 Fetching home timeline (50 tweets)... ✅ Fetched 50 tweets in 2.3s
How It Works twitter-cli extracts all Twitter cookies from your browser, not just authentication tokens. This includes:
auth_token: Your authentication tokenct0: CSRF tokenAll other session cookies for full browser fingerprint
macOS Note : On macOS, Chrome stores cookies in the system Keychain. twitter-cli automatically handles Keychain access by running cookie extraction in the main process.
Cookie Caching Cookies are cached for 24 hours in ~/.cache/twitter-cli/cookies.json to avoid repeated browser access. The cache is automatically:
Refreshed when expired
Invalidated on authentication errors
Re-extracted from browser as needed
Method 2: Environment Variables For automation or server environments where browser access isn’t available.
Extract Cookies from Browser
Open your browser’s Developer Tools:
Go to x.com while logged in
Press F12 to open Developer Tools
Go to the Application tab (Chrome/Edge) or Storage tab (Firefox)
Navigate to Cookies → https://x.com
Find Required Cookies
Look for these two cookies:
auth_token: Your authentication token (long string)ct0: CSRF token (shorter alphanumeric string) Copy their values.
Set Environment Variables
export TWITTER_AUTH_TOKEN = "your_auth_token_here" export TWITTER_CT0 = "your_ct0_token_here"
Add these to your shell config (~/.bashrc, ~/.zshrc, etc.) to make them permanent: # Add to ~/.bashrc or ~/.zshrc export TWITTER_AUTH_TOKEN = "your_auth_token_here" export TWITTER_CT0 = "your_ct0_token_here"
Environment variables take priority over browser cookies. If both are set, environment variables will be used.
Your First Command Let’s fetch your home timeline (“For You” feed):
By default, twitter-cli fetches 50 tweets. You can customize this with the --max flag.
Expected Output You should see a formatted table of tweets:
🔐 Getting Twitter cookies... 📡 Fetching home timeline (50 tweets)... ✅ Fetched 50 tweets in 2.3s ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ 📱 Twitter — 50 tweets ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ @username • 2h ago Tweet content appears here... ❤️ 42 🔄 12 💬 8 👁 1.2K ...
Essential Commands Now that you’re authenticated, try these common operations:
View tweets from accounts you follow (chronological order): twitter feed -t following
See your saved/bookmarked tweets:
Look up any user’s profile: View their tweets: twitter user-posts elonmusk --max 20
Export Data as JSON All read commands support JSON output for scripting and automation:
# Export to stdout twitter feed --json # Save to file twitter feed --json > tweets.json # Or use the -o flag twitter search "machine learning" -o ml_tweets.json
Filter tweets by engagement score:
This ranks tweets using a weighted score based on:
Likes (weight: 1.0)
Retweets (weight: 3.0)
Replies (weight: 2.0)
Bookmarks (weight: 5.0)
Views (logarithmic, weight: 0.5)
Customize scoring in config.yaml (see Configuration ).
Common Authentication Issues
Cookie expired or invalid (HTTP 401/403)
Error : Cookie expired or invalid (HTTP 401)Solution :
Log out and log back into x.com in your browser
twitter-cli will automatically detect and refresh cookies
Or manually invalidate the cache:
rm ~/.cache/twitter-cli/cookies.json
Browser access denied (macOS)
Error : Cookie extraction fails on macOSSolution :
Grant Terminal/your terminal app access to Chrome in System Settings
Go to System Settings → Privacy & Security → Full Disk Access
Add your terminal application
Setting Up a Proxy (Optional) For privacy or to avoid rate limiting, route requests through a proxy:
# HTTP proxy export TWITTER_PROXY = http :// 127 . 0 . 0 . 1 : 7890 # SOCKS5 proxy export TWITTER_PROXY = socks5 :// 127 . 0 . 0 . 1 : 1080
Add to your shell config to make it permanent.
Rate Limiting : Using a proxy doesn’t eliminate rate limits, but can help reduce IP-based restrictions. See Best Practices for more tips.Quick Reference Here are the most common commands:
# Home timeline (For You) twitter feed # Following feed twitter feed -t following # With filtering twitter feed --filter --max 100
Next Steps
Command Reference Explore all available commands and options
Configuration Customize behavior with config.yaml
Best Practices Learn how to avoid bans and rate limits
JSON Export Export data for scripting and automation
