Skip to main content
twitter-cli supports two authentication methods with automatic fallback:
  1. Environment variables (recommended for CI/CD)
  2. Browser cookie extraction (recommended for local development)

​
Authentication Priority

The CLI checks for credentials in this order:
  1. Environment variables (TWITTER_AUTH_TOKEN + TWITTER_CT0)
  2. Cached cookies from previous browser extraction
  3. Live browser cookie extraction
Source: twitter_cli/auth.py:254-299

​
Environment Variables

Set both TWITTER_AUTH_TOKEN and TWITTER_CT0 to authenticate via environment: 
export TWITTER_AUTH_TOKEN="your_auth_token_here"
export TWITTER_CT0="your_ct0_token_here"
Environment variables take priority over browser extraction, making them ideal for scripts and CI pipelines.

​
Finding Your Cookies

1

Open Browser DevTools

Log into x.com and press F12 to open Developer Tools
2

Navigate to Application/Storage

Go to Application → Cookies → https://x.com
3

Copy Cookie Values

Find and copy:
  • auth_token — your session authentication token
  • ct0 — CSRF protection token
4

Set Environment Variables

Export both values:
export TWITTER_AUTH_TOKEN="your_auth_token"
export TWITTER_CT0="your_ct0_value"
The CLI automatically extracts cookies from your browser using browser-cookie3.

​
Supported Browsers

  • Chrome
  • Microsoft Edge
  • Firefox
  • Brave
Source: twitter_cli/auth.py:132-149

​
How It Works

1

In-Process Extraction

First attempts in-process extraction (required on macOS for Keychain access)
2

Subprocess Fallback

Falls back to subprocess extraction if SQLite database is locked
3

Full Cookie Fingerprint

Extracts all Twitter cookies (not just auth_token + ct0) to mimic real browser behavior
4

Cookie Caching

Caches extracted cookies for 24 hours in ~/.cache/twitter-cli/cookies.json

​
Browser Extraction Benefits

Browser extraction provides superior anti-detection:
  • Forwards all Twitter cookies for complete browser fingerprint
  • Includes session cookies like guest_id, personalization_id, etc.
  • Makes requests indistinguishable from actual browser traffic
Source: twitter_cli/auth.py:1-9
Browser cookie extraction requires you to be logged in to x.com in a supported browser.
After loading cookies, the CLI performs lightweight verification: 
verify_cookies(auth_token, ct0, cookie_string)
Verification behavior:
  • Tests cookies against api.x.com/1.1/account/verify_credentials.json
  • Only raises on clear auth failures (401, 403)
  • Tolerates transient errors (404, network issues)
  • Auto-invalidates cache and re-extracts on expiration
Source: twitter_cli/auth.py:42-93 Extracted cookies are cached locally:
  • Location: ~/.cache/twitter-cli/cookies.json
  • TTL: 24 hours
  • Permissions: 0600 (owner read/write only)
Source: twitter_cli/auth.py:302-351

​
Invalidate Cache

To force fresh cookie extraction, delete the cache: 
rm ~/.cache/twitter-cli/cookies.json
Or use the programmatic API: 
from twitter_cli.auth import invalidate_cookie_cache
invalidate_cookie_cache()

​
Troubleshooting

​
No Twitter cookies found

Cause: Not logged into x.com in any supported browser. Solution:
  • Log into x.com in Chrome/Edge/Firefox/Brave
  • Or set TWITTER_AUTH_TOKEN and TWITTER_CT0 manually
Cause: Session expired or token revoked. Solution:
  • Log out and back into x.com
  • Clear ~/.cache/twitter-cli/cookies.json
  • Retry your command

​
macOS Keychain Access Denied

Cause: Chrome encrypts cookies using macOS Keychain, which requires authorization. Solution:
  • Run the CLI from a Terminal with Keychain access
  • Grant access when prompted
  • Or use environment variables instead
Source: twitter_cli/auth.py:118-124

​
Security Best Practices

Never commit cookies or tokens to version control. Cookies provide full account access.
  • Use environment variables for CI/CD
  • Restrict file permissions on cached cookies (0600)
  • Rotate cookies regularly by logging out/in
  • Use browser extraction for local development only
  • Set up proxy to avoid IP exposure (see Proxy Configuration)

​
Next Steps

Config File

Configure YAML settings for fetch, filter, and rate limits

Proxy Setup

Route requests through HTTP/SOCKS5 proxy

Build docs developers (and LLMs) love

Get started for freeTalk to us