https://github.com/zaydiscold/bird

fast cli for twitter/x, by @steipete. mirrored here so the tool stays accessible after the original repo was removed.
https://github.com/zaydiscold/bird

bird cli homebrew safari-cookies twitter x

Last synced: 11 days ago
JSON representation

fast cli for twitter/x, by @steipete. mirrored here so the tool stays accessible after the original repo was removed.

Host: GitHub
URL: https://github.com/zaydiscold/bird
Owner: zaydiscold
License: mit
Created: 2026-03-05T18:54:22.000Z (4 months ago)
Default Branch: main
Last Pushed: 2026-06-08T10:35:50.000Z (12 days ago)
Last Synced: 2026-06-08T12:25:12.520Z (12 days ago)
Topics: bird, cli, homebrew, safari-cookies, twitter, x
Language: TypeScript
Homepage: https://github.com/steipete/bird
Size: 215 KB
Stars: 2
Watchers: 0
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

README

bird

fast cli for twitter/x. built by @steipete. mirrored here so it stays accessible.

what it does · install · usage · ai agents

## what it does

bird is a cli for reading and posting on twitter/x. no api keys. no oauth dance. it reads cookies directly from safari or chrome.

the original [steipete/bird](https://github.com/steipete/bird) repo was removed from github. this mirror exists so people who depend on the tool can still get it. all credit for the cli goes to [@steipete](https://x.com/steipete) (Peter Steinberger). i'm just keeping the lights on.

## install

```bash
# direct download — universal arm64/x86_64 binary from this mirror
curl -L https://github.com/zaydiscold/bird/releases/download/v0.8.0/bird -o bird
chmod +x bird
sudo mv bird /usr/local/bin/bird
```

or with wget:

```bash
wget -O bird https://github.com/zaydiscold/bird/releases/download/v0.8.0/bird
chmod +x bird
sudo mv bird /usr/local/bin/bird
```

> **note on homebrew:** steipete's tap (`brew install steipete/tap/bird`) was the original install method. i'm not sure if that tap is still maintained — it may be down. use the curl install above to be safe.

> _{steipete's original tap: `brew install steipete/tap/bird`}

verify:

```bash
bird whoami # returns your twitter handle
```

requires being logged into x.com in safari or chrome.

## usage

bird auto-detects safari cookies. no setup.

```bash
bird whoami # confirm logged-in account
bird check # check cookie availability
bird --chrome-profile "Default" ... # use chrome instead of safari
```

### read

```bash
bird read # single tweet
bird thread # full conversation thread
bird thread --all # thread, all pages
bird replies # replies to a tweet
bird user-tweets @handle -n 20 # user's recent tweets
```

### search

```bash
bird search "query" -n 20
bird search "from:@handle keyword" -n 10
bird search "term" --all # paginate through everything
```

### timeline

```bash
bird home -n 20 # for you feed
bird home --following -n 20 # following, chronological
bird mentions -n 20 # your mentions
bird bookmarks -n 20 # saved bookmarks
bird likes -n 20 # liked tweets
bird lists # your lists
bird list-timeline # list timeline
bird about @handle # account origin and location
bird following -n 50 # who you follow
bird followers -n 50 # your followers
```

### post

```bash
bird tweet "text here"
bird reply "reply text"
bird follow @handle
bird unfollow @handle

# attach media — up to 4 images or 1 video
bird tweet "caption" --media /path/to/image.jpg --alt "alt text"
bird tweet "caption" --media /path/to/video.mp4

# long posts (X Premium): text over 280 weighted chars is auto-routed
# through CreateNoteTweet — no flag needed, just write a long tweet
bird tweet "$(cat my-long-post.txt)"
```

**long posts / note tweets (new in 0.9.0):** if your text exceeds the standard
280 weighted-char limit (URLs count as 23), `tweet`/`reply` automatically use
X's `CreateNoteTweet` mutation instead of `CreateTweet`. Requires X Premium on
the account. Short tweets are unaffected — they still use the cheap path. The
note-tweet request carries the distinct feature-flag set + `fieldToggles` that
X's web client sends, so it passes server-side validation.

### output

```bash
bird read --json # structured json
bird read --json-full # json + raw api response
bird search "query" --plain # no color, pipeable
```

_{flags: `-n` result count · `--all` paginate · `--following` filter · `--ai-only` curated news · `--with-tweets` include tweets · `--tweets-per-item N` · `--chrome-profile "Name"` · `--json` · `--json-full` · `--plain` · `--media path` · `--alt text`}

## use with ai agents

for claude code, cursor, codex, and other ai agents: **[zaydiscold/bird-skill](https://github.com/zaydiscold/bird-skill)**

i built the skill myself. paste any x.com link into a claude code session and it reads the tweet directly — no browser, no webfetch. it also handles timelines, search, posting, all of it. homegrown, built to work on top of peter's binary.

```bash
npx skills add zaydiscold/bird-skill@bird -g -y
```