189 lines
4.8 KiB
Markdown
189 lines
4.8 KiB
Markdown
# bird 🐦
|
||
|
||
`bird` is a focused command-line tool for posting tweets, replying, and reading tweet details using Twitter/X's GraphQL API. It keeps setup minimal while supporting common workflows for automation or scripting.
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
cd ~/Projects/bird
|
||
pnpm install
|
||
pnpm run binary # Creates the 'bird' executable
|
||
```
|
||
|
||
## Usage
|
||
|
||
### Commands at a glance
|
||
- `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 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.
|
||
|
||
### Examples
|
||
|
||
```bash
|
||
# Show the logged-in account via GraphQL cookies
|
||
bird whoami
|
||
|
||
# Use Firefox profile cookies instead of Chrome
|
||
bird --firefox-profile default-release whoami
|
||
|
||
# Send a tweet
|
||
bird tweet "hello from bird"
|
||
|
||
# Check replies to a tweet
|
||
bird replies https://x.com/user/status/1234567890123456789
|
||
```
|
||
|
||
Global engine switch:
|
||
- `--engine graphql|sweetistics|auto` (default `auto`). `auto` uses Sweetistics when an API key is provided, otherwise falls back to direct GraphQL. `sweetistics` requires `--sweetistics-api-key` (or env) and uses Sweetistics for all commands. `graphql` forces direct Twitter cookies even if an API key is present.
|
||
|
||
You can set persistent defaults via config files (JSON5):
|
||
|
||
- Global: `~/.config/bird/config.json5`
|
||
- Project: `./.birdrc.json5` (overrides global)
|
||
|
||
Example `~/.config/bird/config.json5`:
|
||
|
||
```json5
|
||
{
|
||
// Default to Sweetistics unless overridden by --engine or BIRD_ENGINE
|
||
engine: "sweetistics",
|
||
// Prefer Firefox cookies by default
|
||
firefoxProfile: "default-release",
|
||
// Optional: Sweetistics defaults
|
||
sweetisticsApiKey: "sweet-...",
|
||
sweetisticsBaseUrl: "https://sweetistics.com"
|
||
}
|
||
```
|
||
|
||
Precedence: CLI flags > environment variables > project config > global config.
|
||
|
||
To default to Firefox and Sweetistics, create `~/.config/bird/config.json5`:
|
||
|
||
```json5
|
||
{
|
||
engine: "sweetistics",
|
||
firefoxProfile: "default-release",
|
||
sweetisticsApiKey: "sweet-..."
|
||
}
|
||
```
|
||
|
||
### Post a tweet
|
||
|
||
```bash
|
||
bird tweet "Hello from bird!"
|
||
```
|
||
|
||
### Reply to a tweet
|
||
|
||
```bash
|
||
# Using tweet URL
|
||
bird reply "https://x.com/user/status/1234567890" "This is my reply"
|
||
|
||
# Using tweet ID directly
|
||
bird reply 1234567890 "This is my reply"
|
||
```
|
||
|
||
### Read a tweet
|
||
|
||
```bash
|
||
# Get tweet content by URL or ID
|
||
bird read "https://x.com/user/status/1234567890"
|
||
bird read 1234567890 --json
|
||
```
|
||
|
||
### Search tweets
|
||
|
||
```bash
|
||
# Search for tweets containing a query
|
||
bird search "claude AI" -n 10
|
||
|
||
# Search for mentions of a user
|
||
bird search "@clawdbot"
|
||
```
|
||
|
||
### Find mentions
|
||
|
||
```bash
|
||
# Shortcut to search for @clawdbot mentions
|
||
bird mentions -n 10
|
||
bird mentions --json
|
||
```
|
||
|
||
### Check credentials
|
||
|
||
```bash
|
||
bird check
|
||
```
|
||
|
||
## Authentication
|
||
|
||
`bird` resolves credentials in the following order of priority:
|
||
|
||
1. **CLI arguments** (highest priority)
|
||
```bash
|
||
bird --auth-token "xxx" --ct0 "yyy" tweet "Hello"
|
||
```
|
||
|
||
2. **Environment variables**
|
||
```bash
|
||
export AUTH_TOKEN="xxx"
|
||
export CT0="yyy"
|
||
bird tweet "Hello"
|
||
```
|
||
|
||
Alternative env var names: `TWITTER_AUTH_TOKEN`, `TWITTER_CT0`
|
||
|
||
3. **Chrome cookies** (fallback - macOS only)
|
||
- Automatically extracts from Chrome's cookie database
|
||
- Requires Chrome to be logged into x.com
|
||
- May prompt for keychain access on first run
|
||
|
||
### Posting via Sweetistics (API key)
|
||
|
||
If you have a Sweetistics API key, `bird` can post through the Sweetistics SaaS instead of using local Twitter cookies:
|
||
|
||
```bash
|
||
export SWEETISTICS_API_KEY="sweet-..."
|
||
bird tweet "Hello from Sweetistics!"
|
||
|
||
# Optional: point to a self-hosted instance
|
||
bird --sweetistics-base-url "http://localhost:3000" --sweetistics-api-key "sweet-..." tweet "hi"
|
||
```
|
||
|
||
When an API key is present, `bird` will use Sweetistics’ `/api/actions/tweet` endpoint and skip local cookie resolution.
|
||
|
||
### Getting Your Cookies
|
||
|
||
1. Open Chrome and log into x.com
|
||
2. Open DevTools (Cmd+Option+I)
|
||
3. Go to Application > Cookies > x.com
|
||
4. Copy the values for `auth_token` and `ct0`
|
||
|
||
## Development
|
||
|
||
```bash
|
||
# Run in development mode
|
||
pnpm run dev tweet "Test"
|
||
|
||
# Run tests
|
||
pnpm test
|
||
|
||
# Run linter
|
||
pnpm run lint
|
||
|
||
# Fix lint issues
|
||
pnpm run lint:fix
|
||
```
|
||
|
||
## Notes
|
||
|
||
- Chrome cookie extraction requires macOS (uses `sqlite3` and `security` CLI tools).
|
||
- The keychain access may block when running over SSH; use environment variables instead.
|
||
- Twitter/X rotates GraphQL query IDs; refresh them with `pnpm run graphql:update` (writes `src/lib/query-ids.json`).
|