twitter-cli: Read and Write Twitter/X From the Terminal Without API Keys

What twitter-cli Does and the Problem It Addresses

Twitter's official API has progressively restricted access. Getting a read timeline or bookmarks endpoint requires an approved developer application, and write access requires additional permissions that are not always granted to individual developers. twitter-cli bypasses this entirely by authenticating through the same browser session the user already has.

The README describes the tool's scope: reading timelines (For You and Following feeds), fetching bookmarks, searching tweets with Top/Latest/Photos/Videos tabs, viewing tweet detail and replies, exporting Twitter Articles as Markdown, browsing list timelines, and looking up user profiles, followers, and following. On the write side: posting tweets and replies with optional image attachments, quote-tweeting, deleting tweets, managing likes, managing retweets, and bookmarking.

The README also documents a specific use case for AI agent pipelines: the `--yaml` and `--json` flags produce structured output that can be piped into downstream tools. A non-TTY stdout defaults to YAML automatically, and the SCHEMA.md file in the repository documents the output contract.

Installing and Getting Started

The README recommends uv for installation because it creates an isolated environment:

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

# Alternative: pipx
pipx install twitter-cli

To upgrade to the latest version:

uv tool upgrade twitter-cli
# Or: pipx upgrade twitter-cli

Installing from source requires cloning and running uv sync:

git clone [email protected]:jackwener/twitter-cli.git
cd twitter-cli
uv sync

Once installed, the basic read commands work without any configuration:

# Fetch home timeline (For You)
twitter feed

# Fetch Following timeline
twitter feed -t following

The tool requires Python 3.10 or later. The README advises upgrading regularly to avoid errors from outdated API handling, which is a practical signal that Twitter's internal endpoints change often.

Authentication: Browser Cookies and Environment Variables

twitter-cli uses two authentication methods. The first is automatic browser cookie extraction from Arc, Chrome, Edge, Firefox, or Brave. The README recommends this path because it forwards all Twitter cookies, not just `auth_token` and `ct0`, which aligns the request context more closely with normal browser traffic.

For multi-profile Chrome setups, the profile can be specified with an environment variable:

TWITTER_CHROME_PROFILE="Profile 2" twitter feed

The browser priority can also be set explicitly:

TWITTER_BROWSER=chrome twitter feed

The second authentication method uses environment variables: `TWITTER_AUTH_TOKEN` and `TWITTER_CT0`. The README lists the auth priority: environment variables take precedence over browser extraction. After loading cookies, the CLI performs lightweight verification and fails fast on clear auth errors (401 or 403) rather than making further requests.

Anti-Detection Measures and Rate Limit Handling

twitter-cli includes several measures to reduce the chance of triggering Twitter's bot detection. The README lists: TLS fingerprint impersonation using `curl_cffi` with dynamic Chrome version matching, `x-client-transaction-id` header generation, request timing jitter, and write operation delays of 1.5 to 4 seconds applied randomly.

Proxy support is available via the `TWITTER_PROXY` environment variable:

# HTTP proxy
export TWITTER_PROXY=http://127.0.0.1:7890

# SOCKS5 proxy
export TWITTER_PROXY=socks5://127.0.0.1:1080

The README's best practices section is specific: use a proxy, keep request volumes low with `--max 20` instead of `--max 500`, avoid running too frequently, use browser cookie extraction rather than minimal env-var auth, and avoid datacenter IP addresses because residential proxies are much safer.

The rate limit configuration in `config.yaml` controls the base delay, retry count, and backoff strategy:

rateLimit:
  requestDelay: 2.5     # base delay between requests (randomized ×0.7–1.5)
  maxRetries: 3          # retry count on rate limit (429)
  retryBaseDelay: 5.0    # base delay for exponential backoff
  maxCount: 200          # hard cap on fetched items

Structured Output and the Scoring Filter for Agent Pipelines

The README includes an AI Agent Tip that is concrete: prefer `--yaml` for structured output unless a strict JSON parser is required. A non-TTY stdout defaults to YAML automatically. Both formats follow a documented schema in SCHEMA.md, which covers the full output contract for timelines, bookmarks, search results, and user data.

The optional scoring filter ranks tweets by a configurable engagement formula. The README documents the scoring calculation:

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

Weights are configurable in `config.yaml`. Three filter modes are available: `topN` keeps the highest N tweets by score, `score` keeps tweets above a minimum threshold, and `all` returns all tweets sorted by score. The filter is not applied by default; it requires passing `--filter` or configuring it as the default mode.

This scoring system is useful for building ranked tweet summaries as input to other tools, though the formula treats bookmarks as the highest-weight signal (5.0 by default) and log-scaled views as the lowest (0.5), which reflects a specific judgment about engagement quality.

Limitations, Stability Risk, and Alternatives

The most significant limitation is stability. twitter-cli relies on Twitter's internal web API endpoints and browser behavior, neither of which is documented or guaranteed by Twitter. When Twitter changes its frontend, the tool may stop working until the maintainer updates the API handling. The README acknowledges this directly by recommending frequent upgrades.

The tool carries legal and terms-of-service risk. Twitter's developer agreement governs automated access to the platform. Using a browser-cookie-based approach to bypass the official API is a use case Twitter does not explicitly permit, and the consequences for an account can include rate limiting or suspension. The README does not address this.

A reasonable alternative for structured Twitter data access is Twitter's official API v2 with OAuth 2.0. The official API requires developer account approval and has rate limits, but it provides a stable, documented interface. For developers who need only search results without an account, Twitter's public search API endpoints (subject to their own restrictions) are another path.

For teams that need monitoring rather than scripting, TweetDeck is a browser-based Twitter client that supports multi-column layouts and search queries without requiring API credentials. It does not produce structured output and cannot be used in automated pipelines, but it requires no installation and no workaround for Twitter's API restrictions.

The last push to the repository was on 2026-05-07.

Editorial conclusion

twitter-cli suits developers and researchers who need terminal access to Twitter/X data without registering an API application, and AI pipeline builders who want structured YAML or JSON output from Twitter for downstream processing. It is a poor fit for anyone who needs guaranteed uptime or official rate limit headroom: the tool relies on undocumented browser behavior that Twitter can change at any time, and the README warns explicitly against high request volumes and datacenter IP addresses. Verify that your use case falls within Twitter's terms of service before deploying this in any automated context. The last push was on 2026-05-07.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. public-clis/twitter-cli on GitHub
4. README