bird-fast

bird CLI

一个用于 X/Twitter 的命令行界面，通过现有浏览器会话进行身份验证——无需 API 密钥或 OAuth 设置。

概览

bird 是一个基于 TypeScript 的 CLI，使用 Twitter 的内部 GraphQL API，并自动管理查询 ID。它会从 Safari、Chrome 或 Firefox 提取身份验证 Cookie。

主要功能：

• 通过浏览器 Cookie 实现零配置身份验证
• 完整的推文生命周期：发布、回复、读取、搜索
• 上传媒体（图片、GIF、视频）并添加替代文本
• 多种输出格式（人类可读、JSON、纯文本）
• 自动刷新 GraphQL 查询 ID，并回退到 REST API

适用场景

• 通过脚本或自动化发布推文或回复
• 以编程方式读取和分析推文串
• 搜索提及或特定内容
• 从命令行监控 Twitter 动态

前置条件

• Node.js >= 22 或 Homebrew（用于独立二进制文件）
• 浏览器登录：必须已在 Safari、Chrome 或 Firefox 中登录 x.com

安装

# npm
npm install -g @steipete/bird

# pnpm
pnpm add -g @steipete/bird

# bun
bun add -g @steipete/bird

# Homebrew (macOS — standalone binary, no Node.js required)
brew install steipete/tap/bird

# One-shot execution (no install)
bunx @steipete/bird whoami
npx @steipete/bird whoami

身份验证

bird 使用三级优先级链：

优先级	来源	设置方法
1（最高）	CLI 标志	--auth-token、--ct0
2	环境变量	AUTH_TOKEN、CT0（或 TWITTER_AUTH_TOKEN、TWITTER_CT0）
3（默认）	浏览器 Cookie	自动从 Safari → Chrome → Firefox 提取

验证身份验证：

bird whoami    # Shows authenticated user
bird check     # Shows credential source

快速开始

# Post a tweet
bird tweet "Hello from the terminal!"

# Read a tweet
bird read https://x.com/user/status/1234567890123456789

# Reply to a tweet
bird reply 1234567890123456789 "Great point!"

# Search tweets
bird search "from:elonmusk" -n 20

# View your mentions
bird mentions

命令参考

写入命令

tweet

发布一条新推文，可选附带媒体。

bird tweet "<text>" [options]

# Options
--media <path>    Attach media file (repeatable, up to 4 images/GIFs or 1 video)
--alt <text>      Alt text for corresponding --media (repeatable)

# Examples
bird tweet "Check this out!"
bird tweet "Photo gallery" --media img1.jpg --alt "First photo" --media img2.jpg --alt "Second"
bird tweet "Demo video" --media demo.mp4

reply

回复一条现有推文。

bird reply <tweet-id-or-url> "<text>" [options]

# Examples
bird reply 1234567890123456789 "I agree!"
bird reply https://x.com/user/status/1234567890123456789 "Great thread!"
bird reply 1234567890123456789 "Here's a screenshot" --media shot.png --alt "Screenshot"

读取命令

read

获取单条推文。支持标准推文、Notes（长文）和 Articles。

bird read <tweet-id-or-url>

# Shorthand: just provide the ID or URL
bird 1234567890123456789
bird https://x.com/user/status/1234567890123456789

replies / thread

bird replies <tweet-id-or-url>    # All replies to a tweet
bird thread <tweet-id-or-url>     # Full conversation thread

搜索命令

search

bird search "<query>" [-n <count>]

# Examples
bird search "claude ai" -n 20
bird search "from:anthropic"
bird search "@username"

支持 Twitter 的高级搜索语法：from:、to:、since:、until:、filter:links 等。

mentions / bookmarks

bird mentions [-u <handle>] [-n <count>]    # Mentions of a user (defaults to you)
bird bookmarks [-n <count>]                  # Your bookmarked tweets

实用命令

bird whoami                        # Show authenticated user
bird check                         # Verify credentials and show source
bird query-ids [--fresh] [--json]  # Inspect/refresh GraphQL query ID cache
bird help [command]                # Show help

全局选项

选项	说明
--auth-token <token>	Twitter auth_token Cookie
--ct0 <token>	Twitter ct0 Cookie
--cookie-source <source>	浏览器优先级：safari、chrome、firefox（可重复指定）
--chrome-profile <name>	Chrome 配置文件名称
--firefox-profile <name>	Firefox 配置文件名称
--timeout <ms>	请求超时时间（毫秒）
--plain	稳定输出：禁用 Emoji 和颜色（适用于脚本）
--no-emoji	禁用输出中的 Emoji
--no-color	禁用 ANSI 颜色
--json	以 JSON 格式输出（因命令而异）

媒体附件

类型	扩展名	限制
图片	.jpg、.jpeg、.png、.webp	最多 4 个
GIF	.gif	最多 4 个
视频	.mp4、.m4v、.mov	仅限 1 个

视频不能与图片/GIF 混合使用。

# Alt text for accessibility
bird tweet "Three photos" \
  --media photo1.jpg --alt "Beach sunset" \
  --media photo2.jpg --alt "Mountain view" \
  --media photo3.jpg --alt "City skyline"

输出格式

格式	标志	使用场景
人类可读	（默认）	交互式终端
纯文本	--plain	编写脚本（无 Emoji/颜色）
JSON	--json	以编程方式解析

# Parse tweet data in a script
bird read 1234567890123456789 --json | jq '.text'

# Mention monitoring
bird mentions -n 50 --json | jq '.[] | {user: .user.screen_name, text: .text}'

配置

可选的 JSON5 配置文件：

位置	范围
~/.config/bird/config.json5	全局
./.birdrc.json5	项目专用

// Example config
{
  cookieSource: ["firefox", "safari"],
  firefoxProfile: "default-release",
  timeoutMs: 20000
}

示例

每日自动化脚本

#!/bin/bash
DATE=$(date +"%B %d, %Y")
bird tweet "Daily status for $DATE: All systems operational. #status"

推文串分析

# Get all replies to a viral tweet as JSON
bird replies https://x.com/user/status/1234567890123456789 --json | \
  jq '.[] | {user: .user.screen_name, text: .text, likes: .favorite_count}'

多图产品推文

bird tweet "Product launch gallery 🚀" \
  --media hero.png --alt "Product hero shot" \
  --media feature1.png --alt "Feature overview" \
  --media feature2.png --alt "Technical specs" \
  --media pricing.png --alt "Pricing table"

监控提及并回复

#!/bin/bash
bird mentions -n 20 --json | jq -r '.[] | "\(.id) \(.user.screen_name): \(.text)"'

最佳实践

• 在脚本中使用 --json — 以编程方式解析输出时务必使用
• 在 CI/CD 中使用 --plain — 避免日志中的表情符号和颜色问题
• 添加替代文本 — 附加图片时务必包含 --alt
• 主动刷新查询 ID — 如果几天没有使用 bird，请运行 bird query-ids --fresh
• 为自动化设置环境变量 — 在脚本中使用 AUTH_TOKEN / CT0，而非浏览器 Cookie
• 处理速率限制 — Twitter 会限制请求；在批量自动化脚本中添加延迟（sleep）

故障排除

“未找到身份验证令牌”

# Verify you're logged into x.com in your browser
# Try specifying the browser explicitly
bird whoami --cookie-source safari

# Or set credentials via environment
export AUTH_TOKEN="your-auth-token"
export CT0="your-ct0-token"
bird whoami

GraphQL 404 错误

查询 ID 可能已过期。刷新缓存：

bird query-ids --fresh

错误 226（检测到自动化）

bird 会自动回退到 REST API。如果问题仍然存在，请等待几分钟后重试。

检测到的账号错误

# Multiple browser profiles may have different sessions
bird whoami --cookie-source chrome --chrome-profile "Profile 1"

退出代码

代码	含义
0	成功
1	运行时错误（网络、身份验证、API）
2	用法无效（未知命令、参数错误）

技术说明

• 使用 Twitter 的私有 GraphQL API 端点
• 查询 ID 缓存于 ~/.config/bird/query-ids-cache.json（TTL 为 24 小时）
• 发生 404 错误时自动刷新查询 ID
• 错误 226 时回退到 REST API（statuses/update.json）
• 如果 Twitter 更改内部 API，可能会导致功能失效

资源

• GitHub 仓库 — 源代码和问题反馈
• 更新日志 — 版本历史