124 lines
3.5 KiB
Markdown
124 lines
3.5 KiB
Markdown
# bird 🐦 — fast X CLI for tweeting, replying, and reading
|
|
|
|
`bird` is a fast X CLI for tweeting, replying, and reading. It uses either GraphQL cookies or the Sweetistics API.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
npm install -g @steipete/bird
|
|
# or
|
|
pnpm add -g @steipete/bird
|
|
```
|
|
|
|
## Quickstart
|
|
|
|
```bash
|
|
# Show the logged-in account
|
|
bird whoami
|
|
|
|
# Read a tweet (URL or ID)
|
|
bird read https://x.com/user/status/1234567890123456789
|
|
bird 1234567890123456789 --json
|
|
|
|
# Thread + replies
|
|
bird thread https://x.com/user/status/1234567890123456789
|
|
bird replies 1234567890123456789
|
|
|
|
# Search + mentions
|
|
bird search "from:steipete" -n 5
|
|
bird mentions -n 5
|
|
```
|
|
|
|
## Commands
|
|
|
|
- `bird tweet "<text>"` — post a new tweet.
|
|
- `bird reply <tweet-id-or-url> "<text>"` — reply to a tweet using its ID or URL.
|
|
- `bird read <tweet-id-or-url> [--json]` — fetch tweet content as text or JSON.
|
|
- `bird <tweet-id-or-url> [--json]` — shorthand for `read` when only a URL or ID is provided.
|
|
- `bird replies <tweet-id-or-url> [--json]` — list replies to a tweet.
|
|
- `bird thread <tweet-id-or-url> [--json]` — show the full conversation thread.
|
|
- `bird search "<query>" [-n count] [--json]` — search for tweets matching a query.
|
|
- `bird mentions [-n count] [--json]` — find tweets mentioning @clawdbot.
|
|
- `bird whoami` — print which Twitter account your cookies belong to.
|
|
- `bird check` — show which credentials are available and where they were sourced from.
|
|
|
|
## Engines
|
|
|
|
- `--engine auto` (default) — use GraphQL first; if a Sweetistics API key is available, fall back on errors.
|
|
- `--engine graphql` — use Twitter/X GraphQL with cookies (Chrome/Firefox/env/flags).
|
|
- `--engine sweetistics` — use Sweetistics API key (no browser cookies needed).
|
|
|
|
Global options:
|
|
- `--timeout <ms>`: abort requests after the given timeout (milliseconds).
|
|
|
|
## Authentication (GraphQL)
|
|
|
|
`bird` resolves credentials in this order:
|
|
|
|
1. CLI flags: `--auth-token`, `--ct0`
|
|
2. Environment variables: `AUTH_TOKEN`, `CT0` (fallback: `TWITTER_AUTH_TOKEN`, `TWITTER_CT0`)
|
|
3. Browser cookies (macOS): Firefox or Chrome profiles
|
|
|
|
Browser cookie sources:
|
|
- Firefox (default): `~/Library/Application Support/Firefox/Profiles/<profile>/cookies.sqlite`
|
|
- Chrome: `~/Library/Application Support/Google/Chrome/<Profile>/Cookies`
|
|
|
|
## Config (JSON5)
|
|
|
|
Config precedence: CLI flags > env vars > project config > global config.
|
|
|
|
- Global: `~/.config/bird/config.json5`
|
|
- Project: `./.birdrc.json5`
|
|
|
|
Example `~/.config/bird/config.json5`:
|
|
|
|
```json5
|
|
{
|
|
engine: "auto",
|
|
firefoxProfile: "default-release",
|
|
sweetisticsApiKey: "sweet-...",
|
|
allowFirefox: true,
|
|
allowChrome: false,
|
|
timeoutMs: 20000
|
|
}
|
|
```
|
|
|
|
Environment shortcuts:
|
|
- `SWEETISTICS_API_KEY`, `SWEETISTICS_BASE_URL`
|
|
- `BIRD_ENGINE`, `BIRD_TIMEOUT_MS`
|
|
|
|
## Output
|
|
|
|
- `--json` prints raw tweet objects for read/replies/thread/search/mentions.
|
|
- `read` returns full text for Notes and Articles when present.
|
|
|
|
## Media uploads (Sweetistics only)
|
|
|
|
- Attach media with `--media` (repeatable) and optional `--alt` per item.
|
|
- Up to 4 images, or 1 video (no mixing). Supported: jpg, jpeg, png, webp, gif, mp4, mov.
|
|
|
|
Example:
|
|
|
|
```bash
|
|
bird --engine sweetistics tweet "hi" --media img.png --alt "desc"
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
cd ~/Projects/bird
|
|
pnpm install
|
|
pnpm run build # dist/ + bun binary
|
|
pnpm run build:dist # dist/ only
|
|
pnpm run build:binary
|
|
|
|
pnpm run dev tweet "Test"
|
|
pnpm test
|
|
pnpm run lint
|
|
```
|
|
|
|
## Notes
|
|
|
|
- GraphQL uses internal X endpoints and can be rate limited (429).
|
|
- Query IDs rotate; refresh them with `pnpm run graphql:update`.
|