From 0bd99717be291df7e7edd2bb65e45608685585e5 Mon Sep 17 00:00:00 2001 From: George Zhang Date: Tue, 20 Jan 2026 03:49:40 +0800 Subject: [PATCH] docs(bird): update skill for v0.5-0.8 features - Add 18 missing commands (home, news, lists, engagement, etc.) - Document pagination, media uploads, output options - Add config file format and library usage - Update posting advice (engagement actions now work) - Add troubleshooting section --- skills/bird/SKILL.md | 250 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 198 insertions(+), 52 deletions(-) diff --git a/skills/bird/SKILL.md b/skills/bird/SKILL.md index 07bcedac1..d4f402321 100644 --- a/skills/bird/SKILL.md +++ b/skills/bird/SKILL.md @@ -1,77 +1,223 @@ --- name: bird -description: X/Twitter CLI for reading, searching, and posting via cookies or Sweetistics. +description: X/Twitter CLI for reading, searching, posting, and engagement via cookies. homepage: https://bird.fast -metadata: {"clawdbot":{"emoji":"🐦","requires":{"bins":["bird"]},"install":[{"id":"brew","kind":"brew","formula":"steipete/tap/bird","bins":["bird"],"label":"Install bird (brew)"}]}} +metadata: {"clawdbot":{"emoji":"🐦","requires":{"bins":["bird"]},"install":[{"id":"brew","kind":"brew","formula":"steipete/tap/bird","bins":["bird"],"label":"Install bird (brew)"},{"id":"npm","kind":"npm","package":"@steipete/bird","bins":["bird"],"label":"Install bird (npm)"}]}} --- -# bird +# bird 🐦 -## Reading vs Writing - Different Tools +Fast X/Twitter CLI using GraphQL + cookie auth. No API keys needed. -**For READING tweets** (works great): -- Use the `bird` CLI - it's fast and reliable -- `bird read ` - grab a specific tweet -- `bird search "query" -n 5` - search tweets -- `bird mentions` - check notifications - -**For WRITING tweets** (here's where it gets spicy): -- **Don't use the CLI for posting** - Twitter flags it as automated and you'll get rate limited or soft-banned fast -- **Use the browser tool instead** - mimics real human behavior - -## Quick Reference (Reading Only) +## Install ```bash -bird whoami # Check auth status -bird read # Read a specific tweet -bird thread # Read full thread -bird search "query" -n 5 # Search tweets -bird mentions # Check notifications +# npm/pnpm/bun (Node ≥ 20) +npm install -g @steipete/bird + +# Homebrew (macOS, prebuilt binary) +brew install steipete/tap/bird + +# One-shot (no install) +bunx @steipete/bird whoami ``` -## The React Input Problem +## Authentication -Twitter's compose box is a React controlled input. You can't just set `.value` like a normal input - React ignores it. The workaround: +`bird` uses your existing browser session (cookie auth). No password prompt. -**Simulate a paste event:** -```javascript -// 1. Focus the editor -var editor = document.querySelector('[data-testid="tweetTextarea_0"]'); -editor.focus(); +Resolution order: +1. CLI flags: `--auth-token`, `--ct0` +2. Environment: `AUTH_TOKEN`, `CT0` +3. Browser cookies via `--cookie-source` (default: Safari → Chrome → Firefox) -// 2. Create a fake paste event (this triggers React's state update) -var dataTransfer = new DataTransfer(); -dataTransfer.setData('text/plain', 'your tweet text here'); -var pasteEvent = new ClipboardEvent('paste', { - clipboardData: dataTransfer, - bubbles: true, - cancelable: true -}); -editor.dispatchEvent(pasteEvent); +For Chromium variants (Arc/Brave), use `--chrome-profile-dir `. -// 3. Click the post button -document.querySelector('[data-testid="tweetButtonInline"]').click(); +## Commands + +### Account & Auth + +```bash +bird whoami # Show logged-in account +bird check # Show credential sources +bird query-ids --fresh # Refresh GraphQL query ID cache ``` -## Browser Setup Notes +### Reading Tweets -- Use a dedicated browser profile (e.g. "clawd") so you're logged in persistently -- The cookie config lives at `~/.config/bird/config.json5` for the CLI -- If CDP fails, kill Chrome completely (`pkill -9 "Google Chrome"`) and restart with `browser action=start` +```bash +bird read # Read a single tweet +bird # Shorthand for read +bird thread # Full conversation thread +bird replies # List replies to a tweet +``` -## Rate Limiting & Detection +### Timelines -- Space out your posts - don't rapid-fire -- Vary your timing slightly (don't post at exactly :00 every hour) -- If you get flagged, the account might need a CAPTCHA solve manually -- Reading is basically unlimited, posting is where they watch you +```bash +bird home # Home timeline (For You) +bird home --following # Following timeline +bird user-tweets @handle -n 20 # User's profile timeline +bird mentions # Tweets mentioning you +bird mentions --user @handle # Mentions of another user +``` -## Selectors That Work (as of late 2025) +### Search -- Tweet compose box: `[data-testid="tweetTextarea_0"]` -- Post button: `[data-testid="tweetButtonInline"]` -- These change occasionally so if stuff breaks, inspect the page +```bash +bird search "query" -n 10 +bird search "from:steipete" --all --max-pages 3 +``` + +### News & Trending + +```bash +bird news -n 10 # AI-curated from Explore tabs +bird news --ai-only # Filter to AI-curated only +bird news --sports # Sports tab +bird news --with-tweets # Include related tweets +bird trending # Alias for news +``` + +### Lists + +```bash +bird lists # Your lists +bird lists --member-of # Lists you're a member of +bird list-timeline -n 20 # Tweets from a list +``` + +### Bookmarks & Likes + +```bash +bird bookmarks -n 10 +bird bookmarks --folder-id # Specific folder +bird bookmarks --include-parent # Include parent tweet +bird bookmarks --author-chain # Author's self-reply chain +bird bookmarks --full-chain-only # Full reply chain +bird unbookmark +bird likes -n 10 +``` + +### Social Graph + +```bash +bird following -n 20 # Users you follow +bird followers -n 20 # Users following you +bird following --user # Another user's following +bird about @handle # Account origin/location info +``` + +### Engagement Actions + +```bash +bird follow @handle # Follow a user +bird unfollow @handle # Unfollow a user +``` + +The library also exposes like/unlike/retweet/unretweet/bookmark mutations. + +### Posting + +```bash +bird tweet "hello world" +bird reply "nice thread!" +bird tweet "check this out" --media image.png --alt "description" +``` + +**⚠️ Posting risks**: Twitter may flag automated posting (error 226). `bird` falls back to legacy endpoints, but for high-volume or sensitive posting, consider using the browser tool instead. + +## Media Uploads + +```bash +bird tweet "hi" --media img.png --alt "description" +bird tweet "pics" --media a.jpg --media b.jpg # Up to 4 images +bird tweet "video" --media clip.mp4 # Or 1 video +``` + +Supported: jpg, jpeg, png, webp, gif, mp4, mov. + +## Pagination + +Commands supporting pagination: `replies`, `thread`, `search`, `bookmarks`, `likes`, `list-timeline`, `following`, `followers`, `user-tweets` + +```bash +bird bookmarks --all # Fetch all pages +bird bookmarks --max-pages 3 # Limit pages +bird bookmarks --cursor # Resume from cursor +bird replies --all --delay 1000 # Delay between pages (ms) +``` + +## Output Options + +```bash +--json # JSON output +--json-full # JSON with raw API response +--plain # No emoji, no color (script-friendly) +--no-emoji # Disable emoji +--no-color # Disable ANSI colors (or set NO_COLOR=1) +--quote-depth n # Max quoted tweet depth in JSON (default: 1) +``` + +## Global Options + +```bash +--auth-token # Set auth_token cookie +--ct0 # Set ct0 cookie +--cookie-source # safari|chrome|firefox (repeatable) +--chrome-profile # Chrome profile name +--chrome-profile-dir # Chromium profile dir (Arc/Brave) +--firefox-profile # Firefox profile +--timeout # Request timeout +--cookie-timeout # Cookie extraction timeout +``` + +## Config File + +`~/.config/bird/config.json5` (global) or `./.birdrc.json5` (project): + +```json5 +{ + cookieSource: ["safari", "chrome"], + chromeProfileDir: "/path/to/Arc/Profile", + timeoutMs: 20000, + quoteDepth: 1 +} +``` + +Environment variables: `BIRD_TIMEOUT_MS`, `BIRD_COOKIE_TIMEOUT_MS`, `BIRD_QUOTE_DEPTH` + +## Library Usage + +```typescript +import { TwitterClient, resolveCredentials } from '@steipete/bird'; + +const { cookies } = await resolveCredentials({ cookieSource: 'safari' }); +const client = new TwitterClient({ cookies }); + +const searchResult = await client.search('from:steipete', 50); +const newsResult = await client.getNews(10, { aiOnly: true }); +``` + +## Troubleshooting + +### Query IDs stale (404 errors) +```bash +bird query-ids --fresh +``` + +### Cookie extraction fails +- Check browser is logged into X +- Try different `--cookie-source` +- For Arc/Brave: use `--chrome-profile-dir` + +### Rate limited (429) +- Space out requests +- Reading is generous; posting/engagement is watched more closely + +### Error 226 on posting +Twitter flagged as automated. `bird` auto-retries with legacy endpoint, but may still fail. Use browser for reliable posting. --- -**TL;DR: read with CLI, write with browser + paste hack.** 🐦 +**TL;DR**: Read/search/engage with CLI. Post carefully or use browser. 🐦