A fast, friendly command line for X (Twitter). One pure-Go binary that reads tweets, profiles, timelines, threads, and search over X's free public surfaces and crawls accounts into a local SQLite store. Strictly read-only: it never writes to your account. No paid API, nothing to sign up for.
Install • Commands • Output • Session • Guides
Documentation: https://x-cli.tamnd.com (mirror: https://tamnd.github.io/x-cli)
x tweet 20 # a single tweet
x user nasa # a profile
x timeline nasa --guest -n 20 # a user's recent tweets
x thread 1903142823316049977 # the conversation around it, root first
x media https://x.com/nasa/status/2064422103416238295 --download .
x timeline nasa -o url | xargs -n1 x getx speaks only X's own free, public surfaces, the same ones a logged-out browser uses, across three tiers. It picks the cheapest one that can answer each call:
- Tier 0, syndication. The public embed/syndication endpoint. No auth at all. Serves single tweets, profiles, and the recent timeline window.
- Tier 1, guest GraphQL. An opt-in (
--guest) guest token, minted the same way the web client mints one. X has narrowed what it answers for one: as of July 2026 it is five operations, the profile read by handle or by id, the deeper timeline walk, the tweet read, and an audio Space. Everything else on that surface comes back 404. - Tier 2, session GraphQL. Your own browser session cookies, imported with
x auth import. Unlocks reads X reserves for logged-in clients: search, followers/following, your home timeline, and bookmarks.
There is no developer API key and no paid plan anywhere in the tool, and the tool only ever reads. It has no commands that post, like, follow, or otherwise change your account.
Grab a binary from the releases (archives for Linux, macOS and Windows on amd64 and arm64, plus deb, rpm and apk), or:
go install github.com/tamnd/x-cli/cmd/x@latest
docker run --rm ghcr.io/tamnd/x:latest tweet 20Or build from source:
git clone https://github.com/tamnd/x-cli
cd x-cli
make build # produces ./bin/xx is pure Go (CGO_ENABLED=0); the binary has no runtime dependencies.
Shell completion is built in: x completion bash|zsh|fish|powershell.
The everyday reads. The tier column shows the cheapest tier that can answer:
Tier 0 needs nothing, g needs --guest, s needs a session.
| Command | Reads | Tier |
|---|---|---|
x get <ref>... |
whatever the reference points at, read by the command that fits | 0 |
x tweet <ref> |
a single tweet | 0 |
x user <user> |
a profile | 0 |
x timeline <user> |
a user's tweets (deeper with --guest) |
0 |
x thread <ref> |
the conversation around a tweet, root first | 0 |
x replies <ref> |
the replies to a tweet, or a user's own replies | 0 |
x media <ref> |
the pictures and video on a tweet or a profile, --download for the bytes |
0 |
x search <query> |
search tweets | s |
x counts <query> |
per-day tweet counts for a search | s |
x followers <user> / x following <user> |
the follow graph | s |
x likers <ref> / x retweeters <ref> |
who liked or retweeted | s |
x home / x bookmarks |
your home timeline, your bookmarks | s |
x space <ref> |
an audio Space: hosts, speakers, times, audience | g |
x trends [woeid] / x places [query] |
what is trending in a place, and the places there are | 0 |
x embed <ref> |
a tweet's oEmbed blockquote, verbatim | 0 |
x download <ref> |
a tweet's media to disk | 0 |
x edges <ref>... |
the graph claims a record makes, one read and no walking | 0 |
x graph <ref>... |
those claims and the nodes they address, as one document | 0 |
x rdf <ref>... |
the same graph as RDF: nt, ttl, jsonld, nq | 0 |
x crawl <seed>... |
breadth-first crawl into the local store | 0 |
x query <sql> |
query what you have collected | local |
x serve exposes the reads over HTTP as NDJSON, one route each under /v1/, and
x mcp exposes the same 24 as MCP tools for an agent. Both take the global
flags, so the tier you serve at is the one you pass.
x also says what it knows about itself, from the same tables it routes on:
x tiers for what each credential buys, x routes for which surface answers
which question, x surfaces for the limits and cache lives, x fields tweet
for which surface fills which field, and x doctor to ask all eight live. See
the CLI reference for the full surface
and every flag.
Every command speaks one normalized data model and renders it the way your pipeline wants. The default is a readable list of sections on a terminal and JSONL when piped.
x timeline nasa --guest # each tweet as a section (default)
x timeline nasa --guest -o table # aligned columns in a grid
x timeline nasa --guest -o jsonl # one JSON object per line
x timeline nasa --guest -o csv --fields id,likes,text
x timeline nasa --guest -o url # just the permalinks
x user nasa --template '{{.username}} {{.metrics.followers}}'Tweet and account IDs are always strings, so a snowflake never loses precision
in jq or a spreadsheet.
Some reads X reserves for logged-in clients (search, followers/following, your home timeline, bookmarks). Import your session once from your browser cookies:
x auth import --auth-token <auth_token> --ct0 <ct0>
x auth statusThen, for example:
x search "site reliability" -n 50 -o jsonl
x followers nasa -n 100 -o csv --fields username,name,followers
x home -n 50 -o jsonlYour session is used only to read. The tool has no command that posts, likes, follows, or otherwise changes your account.
x crawl walks the graph breadth-first into a local SQLite store, x discover --store tees a live walk into the same place, and x query runs SQL back over
it without touching the network. The store is x.db under the data dir; point
--data-dir somewhere else to keep crawls apart.
x crawl nasa --depth 1 --max 200
x discover nasa --follow network --depth 2 --store
x db stats
x query "select predicate, count(*) from edges group by 1 order by 2 desc"
x export --format nq > nasa.nq # the whole store as RDFThe full documentation lives at x-cli.tamnd.com. The guides walk through each area in depth:
- Reading tweets: tweets, profiles, timelines, and threads, and which tier each needs.
- Search and discovery: search, counts, the follow graph, likers, and retweeters.
- Your session: import your browser cookies to unlock the session-only reads.
- Output and pipelines: the formats,
--fields, templates, and feedingjq. - The local store: turn any read into a crawl and query it back with SQL.
For the complete command and flag map, see the CLI reference and output formats.
x is derived from nitter and is licensed under the GNU AGPL-3.0. See LICENSE and NOTICE.