twitter-cli

Twitter/X CLI tool. Read, search, post, and interact with Twitter — cookie-based auth, no API keys needed.

Installed via: uv tool install twitter-cli (binary at ~/.local/bin/twitter)

Tool

export PATH="$HOME/.local/bin:$PATH"
twitter <command> [args]

Commands

Search

# Basic search
twitter search "AI agents" -n 20 --json

# Advanced filters
twitter search "python" --from elonmusk --json
twitter search "AI" --lang en --since 2026-01-01 --until 2026-03-01
twitter search "rust" --has links --min-likes 100
twitter search --from bbc --exclude retweets -n 50

# Search types: top (default), latest, photos, videos
twitter search "breaking news" -t latest --json

Feed (Timeline)

twitter feed -n 20 --json                  # algorithmic (for-you)
twitter feed -t following -n 30 --json     # chronological
twitter feed -o timeline.json              # save to file
twitter feed -i timeline.json --filter     # reload + filter

View Tweet & Replies

twitter tweet 1234567890 --json            # by ID
twitter tweet "https://x.com/user/status/1234567890" --json  # by URL
twitter tweet 1234567890 -n 50 --json      # with up to 50 replies

Post / Reply / Quote / Retweet

twitter post "Hello world!" --json
twitter post "With image" -i photo.jpg --json
twitter post "Gallery" -i a.png -i b.png -i c.jpg   # up to 4 images

twitter reply 1234567890 "Great point!" --json
twitter quote 1234567890 "Adding context" --json
twitter retweet 1234567890 --json

User Profiles & Posts

twitter user elonmusk --json               # profile info
twitter user-posts elonmusk -n 20 --json   # user's tweets
twitter whoami --json                      # current auth user

Social Graph

twitter followers elonmusk -n 100 --json
twitter following elonmusk -n 100 --json
twitter follow username --json
twitter unfollow username --json

Engagement

twitter like 1234567890 --json
twitter unlike 1234567890 --json
twitter bookmark 1234567890 --json
twitter unbookmark 1234567890 --json

Bookmarks & Likes

twitter bookmarks -n 50 --json
twitter likes myhandle -n 50 --json        # own likes only (others' likes are private since June 2024)

Articles

twitter article 1234567890 --markdown      # render as markdown
twitter article 1234567890 -o article.md   # save to file
twitter article 1234567890 --json

Delete

twitter delete 1234567890 --json

Diagnostics

twitter status                             # check auth
twitter whoami --json                      # current user info
twitter doctor                             # full diagnostics (cookie extraction, auth)

Auth

Cookie-based authentication. The CLI extracts cookies from the local browser automatically (no API keys or OAuth needed).

Run twitter doctor to diagnose auth issues
Run twitter status to check if authenticated
Cookies are extracted from the system browser — user must be logged into twitter.com/x.com

Output

Flag	Format	Use case
(none)	Table (human-readable)	Interactive display
`--json`	JSON	Agent parsing (preferred)
`--yaml`	YAML	Alternative structured output
`-c/--compact`	Minimal fields	LLM-friendly, reduced tokens
`--full-text`	Full tweet text in table	Avoid truncation in table mode

For agent usage, always use --json for structured parsing.

Behavior Notes

Always prepend export PATH="$HOME/.local/bin:$PATH" before calling twitter
Use --json for all programmatic access — parse the JSON output
-n/--max controls result count; omitting it uses the CLI default
--filter enables score-based relevance filtering (search, feed, bookmarks)
-o/--output saves raw JSON to file for later reprocessing (-i/--input)
Tweet IDs and full URLs are interchangeable for tweet, article commands
likes only works for the authenticated user (Twitter made likes private June 2024)
Write operations (post, reply, like, follow, etc.) require user confirmation before executing
Images: up to 4 per post/reply/quote via -i/--image