bird/README.md

# bird 🐦

`bird` is a fast X CLI for tweeting, replying, and reading — powered by cookies or Sweetistics.

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

### Browser cookie sources (macOS)

- **Chrome (default)**: reads `~/Library/Application Support/Google/Chrome/<Profile>/Cookies` (WAL/SHM copied too). Select with `--chrome-profile <name>`; defaults to `Default` or whatever you set in config.
- **Firefox**: reads `~/Library/Application Support/Firefox/Profiles/<profile>/cookies.sqlite`. Select with `--firefox-profile <name>`; defaults to `*.default-release` if present. Use this when Chrome isn’t logged in.

Precedence still holds: CLI flags > env vars > project config > global config. So a one-off `--firefox-profile default-release` overrides any config defaults.

### 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`).