twitter-cli supports routing all API requests through a proxy using the TWITTER_PROXY environment variable.
Using a proxy is highly recommended to reduce IP-based rate limiting and ban risk.
Setup Set the TWITTER_PROXY environment variable before running any command:
export TWITTER_PROXY = "http://127.0.0.1:7890"
Source: README.md:135-148
Supported Proxy Types HTTP Proxy export TWITTER_PROXY = "http://127.0.0.1:7890"
HTTPS Proxy export TWITTER_PROXY = "https://proxy.example.com:8443"
SOCKS5 Proxy export TWITTER_PROXY = "socks5://127.0.0.1:1080"
Authenticated Proxy Common Proxy Software Clash Clash typically runs on port 7890:
export TWITTER_PROXY = "http://127.0.0.1:7890" twitter feed
V2Ray V2Ray SOCKS5 typically runs on port 1080:
export TWITTER_PROXY = "socks5://127.0.0.1:1080" twitter feed
SSH Tunnel Create a SOCKS5 tunnel:
Set proxy
export TWITTER_PROXY = "socks5://127.0.0.1:1080"
Shadowsocks Shadowsocks local client on port 1080:
export TWITTER_PROXY = "socks5://127.0.0.1:1080" twitter search "trending topic"
Persistent Configuration Add to your shell profile for automatic proxy usage:
Bash/Zsh Add to ~/.bashrc or ~/.zshrc:
# Twitter CLI proxy export TWITTER_PROXY = "http://127.0.0.1:7890"
Reload:
source ~/.bashrc # or ~/.zshrc
Fish Add to ~/.config/fish/config.fish:
# Twitter CLI proxy set -gx TWITTER_PROXY "http://127.0.0.1:7890"
Reload:
source ~/.config/fish/config.fish
Testing Proxy Connection Verify proxy connectivity before running commands:
Using curl curl -x " $TWITTER_PROXY " https://api.x.com/1.1/help/configuration.json
Expected: JSON response with Twitter configuration
export TWITTER_PROXY = "http://127.0.0.1:7890" twitter user twitter # Fetch official Twitter account
If successful, your proxy is working.
Proxy Best Practices Do not use datacenter IPs . Twitter/X flags cloud provider IPs. Use residential proxies or personal VPN.
Recommended Proxy Types
Residential proxies — Real user IPs, lowest ban riskMobile proxies — Cellular IPs, good for high-volume usagePersonal VPN — Consistent IP with normal usage patternsSSH tunnel to home — Safe if home IP has clean history
Avoid
Public proxies — Often blacklisted
Datacenter IPs — AWS, GCP, DigitalOcean easily detected
Free VPNs — Shared by many users, high ban risk
TOR exit nodes — Blocked by Twitter
Rate Limiting with Proxy Proxies help avoid IP bans but don’t bypass account-level rate limits:
# config.yaml rateLimit : requestDelay : 3.0 # Increase delay when using proxy maxRetries : 3 retryBaseDelay : 10.0 # Longer backoff for proxy retry maxCount : 100 # Lower cap to stay under limits
Source: README.md:199-205
Combine proxy with conservative rateLimit config for maximum safety.
Debugging Proxy Issues Connection refused Cause : Proxy not running or wrong port.Solution :# Check if proxy is listening netstat -an | grep 7890 # Or use lsof lsof -i :7890
Timeout errors Cause : Proxy is slow or blocking Twitter domains.Solution :
Test proxy with curl -x $TWITTER_PROXY https://x.com
Try different proxy server
Increase timeout in proxy software
407 Proxy Authentication Required Cause : Proxy requires credentials but none provided.Solution :Certificate errors Cause : HTTPS proxy with self-signed certificate.Solution :
Use HTTP proxy instead: http:// not https://
Or install proxy CA certificate
Environment Variable Priority If both TWITTER_PROXY and system proxy variables are set:
# twitter-cli uses TWITTER_PROXY export TWITTER_PROXY = "http://127.0.0.1:7890" # System proxy (ignored by twitter-cli) export http_proxy = "http://other-proxy.com:8080" export https_proxy = "http://other-proxy.com:8080" twitter feed # Uses TWITTER_PROXY, not http_proxy
TWITTER_PROXY takes precedence over http_proxy and https_proxy.
Proxy with Docker When running in Docker, pass TWITTER_PROXY as environment variable:
docker run -e TWITTER_PROXY="http://host.docker.internal:7890" \ twitter-cli feed
Use host.docker.internal to access host machine’s proxy from Docker.
Disabling Proxy Temporarily Unset the variable to disable proxy for one command:
# With proxy export TWITTER_PROXY = "http://127.0.0.1:7890" twitter feed # Without proxy (temporary) env -u TWITTER_PROXY twitter feed # Permanently disable unset TWITTER_PROXY
Security Considerations Never use untrusted proxies . Proxies can intercept authentication cookies and account credentials.
Proxy Security Checklist
Only use proxies you control or from trusted providers
Avoid free public proxies — they may log/steal credentials
Use SOCKS5 over HTTP when possible (less inspection)
Rotate proxy IPs periodically
Monitor proxy logs for suspicious activity
Use HTTPS endpoints to encrypt data between proxy and Twitter
Advanced: Per-Command Proxy Override proxy for specific commands:
# Default proxy for most commands export TWITTER_PROXY = "http://127.0.0.1:7890" # Use different proxy for one command TWITTER_PROXY = "socks5://127.0.0.1:1080" twitter search "sensitive topic" # Disable proxy for one command TWITTER_PROXY = "" twitter feed
Proxy + Authentication Combine proxy with browser cookie extraction:
# Set proxy export TWITTER_PROXY = "http://127.0.0.1:7890" # Cookies auto-extracted from browser twitter feed # Or use environment auth export TWITTER_AUTH_TOKEN = "your_token" export TWITTER_CT0 = "your_ct0" twitter feed
See Authentication for cookie setup.
Troubleshooting Checklist
Verify proxy is running
curl -x " $TWITTER_PROXY " https://httpbin.org/ip
Should return your proxy’s IP
Test Twitter API access
curl -x " $TWITTER_PROXY " https://api.x.com/1.1/help/configuration.json
Should return JSON config
Check proxy format
Ensure correct format:
HTTP: http://host:port
SOCKS5: socks5://host:port
No trailing slash
Test with twitter-cli
Should fetch Twitter’s official account Next Steps
Authentication Set up cookies and tokens
Config File Configure rate limits and retries
