Skip to content
x

Quick start

From an empty terminal to a real tweet, a timeline, shaped output, and a downloaded image.

This walks the core loop: read a tweet with no setup, look at a profile and timeline, shape the output, and download some media. Every command here hits live data and finishes in a second or two. None of it needs auth except where noted.

1. Read a tweet

x tweet 20

## 20
- created: 2006-03-21 20:50
- author: jack
- likes: 309822
- rt: 124855
- replies: 17962
- text: just setting up my twttr
- url: https://x.com/jack/status/20

That is Tier 0, no auth at all, and it is two surfaces rather than one: the syndication endpoint has the tweet and x.com's own page has the counts X stopped putting in the embed. A profile works the same way:

x user nasa

prints the handle, name, bio, and follower and following counts.

2. Follow a timeline

x timeline nasa -n 10

Tier 0 gives you a recent window of a user's tweets. To page deeper, opt into the guest tier:

x timeline nasa --guest -n 50

x mints a guest token (cached for next time) and pages further back. Add --replies to include replies or --media to keep only tweets with media.

3. Shape the output

On a terminal you get the readable list above, one section per record. Pick another shape with -o:

x timeline nasa -o url            # just the tweet URLs, one per line
x timeline nasa -o jsonl          # one JSON object per row (default when piped)
x timeline nasa --fields id,text  # project just the columns you want

Pipe JSONL into jq. IDs are strings, so they stay exact:

x timeline nasa --guest -o jsonl | jq -r '.id + "  " + .text'

Render each row yourself with a Go template:

x timeline nasa --template '{{.id}} {{.author.username}}: {{.text}}'

4. Download media

x download pulls a tweet's images and video to disk:

x download 20 -O ./media

It writes each attachment under the output directory and prints the paths it wrote. x media does the same job for a whole profile, and lists the URLs first when you want to look before you fetch:

x media nasa -o url                    # what is there
x media nasa --download ./media        # the bytes

Both save the original upload by default. Pass --size small for X's re-encode when the full-resolution file is more than you need.

Where to next

You have the core loop. From here:

3 min read