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

> twitter-cli is a Python command-line tool for reading Twitter/X timelines, bookmarks, and search results and for posting, liking, and retweeting without registering an API application. It authenticates by extracting browser cookies directly and uses TLS fingerprint impersonation to reduce detection risk.

**public-clis/twitter-cli** — A CLI for Twitter/X — feed, bookmarks, and user timeline in terminal

- Repository: https://github.com/public-clis/twitter-cli
- Stars: 2,956 · Forks: 286
- Language: Python
- License: Apache-2.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/public-clis-twitter-cli

## 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:

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

# Alternative: pipx
pipx install twitter-cli
```

To upgrade to the latest version:

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

Installing from source requires cloning and running uv sync:

```bash
git clone git@github.com:jackwener/twitter-cli.git
cd twitter-cli
uv sync
```

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

```bash
# 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:

```bash
TWITTER_CHROME_PROFILE="Profile 2" twitter feed
```

The browser priority can also be set explicitly:

```bash
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:

```bash
# 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:

```yaml
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:

```text
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.

## 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.

## FAQ

### Does twitter-cli require a Twitter API key?

The README states that twitter-cli authenticates using browser cookies rather than an API key. It extracts cookies automatically from Arc, Chrome, Edge, Firefox, or Brave. Environment variables TWITTER_AUTH_TOKEN and TWITTER_CT0 are also supported as an alternative.

### Can twitter-cli be used in AI agent pipelines for structured data?

The README documents --yaml and --json flags that produce structured output following a schema defined in SCHEMA.md. A non-TTY stdout defaults to YAML automatically. The README includes an AI Agent Tip recommending --yaml for most agent use cases, and the --max flag limits result count for more predictable pipeline behavior.

### What are the account ban risks with twitter-cli?

The README does not address Twitter's terms of service. The tool bypasses the official API by using browser cookies and TLS fingerprint impersonation, which Twitter does not explicitly permit under its developer agreement. The README recommends using a proxy, keeping request volumes low, avoiding datacenter IP addresses, and running infrequently to reduce the chance of detection.

## Sources

- [Issues](https://github.com/public-clis/twitter-cli/issues)
- [License: Apache-2.0](https://github.com/public-clis/twitter-cli/blob/main/LICENSE)
- [public-clis/twitter-cli on GitHub](https://github.com/public-clis/twitter-cli)
- [README](https://github.com/public-clis/twitter-cli/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/public-clis-twitter-cli