Back to Details

bird

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bird - X/Twitter CLI

Bird - X/Twitter 命令行工具

Guide for using the 
bird
CLI tool to interact with X/Twitter content.
使用
bird
命令行工具与X/Twitter内容交互的指南。

Quick Start

快速开始

Install bird globally:
bash
npm install -g @steipete/bird
全局安装Bird：
bash
npm install -g @steipete/bird

or

or

pnpm add -g @steipete/bird
pnpm add -g @steipete/bird

or

or

bun add -g @steipete/bird
bun add -g @steipete/bird

one-shot (no install)

一次性使用（无需安装）

bunx @steipete/bird whoami
bunx @steipete/bird whoami

or

or

brew install steipete/tap/bird

Verify authentication:
```bash
bird whoami          # Show logged-in account
bird check           # Check available credentials
brew install steipete/tap/bird

验证身份：
```bash
bird whoami          # 显示当前登录账户
bird check           # 检查可用凭证

Common Tasks

常见操作

Read Tweets and Threads

查看推文与推文线程

bash
undefined
bash
undefined

Read a single tweet

查看单条推文

bird read <tweet-url-or-id> bird <tweet-url-or-id> # shorthand
bird read <tweet-url-or-id> bird <tweet-url-or-id> # 简写形式

Read a thread (tweet + replies)

查看推文线程（推文+回复）

bird thread <tweet-url-or-id>
bird thread <tweet-url-or-id>

Get replies only

仅查看回复内容

bird replies <tweet-url-or-id>
bird replies <tweet-url-or-id>

Output as JSON for processing

以JSON格式输出以便处理

bird read <id> --json bird thread <id> --json --max-pages 3
undefined
bird read <id> --json bird thread <id> --json --max-pages 3
undefined

Search Tweets

搜索推文

bash
undefined
bash
undefined

Basic search

基础搜索

bird search "query" -n 10
bird search "query" -n 10

Search from a specific user

搜索特定用户的内容

bird search "from:username" -n 20
bird search "from:username" -n 20

Get all results (paginated)

获取所有结果（分页）

bird search "query" --all --json
bird search "query" --all --json

Search with date filters

按日期筛选搜索

bird search "query since:2024-01-01" -n 50
undefined
bird search "query since:2024-01-01" -n 50
undefined

Get User Content

获取用户内容

bash
undefined
bash
undefined

User's tweets

用户推文

bird user-tweets @username -n 20 bird user-tweets @username -n 50 --json
bird user-tweets @username -n 20 bird user-tweets @username -n 50 --json

User mentions

用户提及内容

bird mentions --user @username -n 10
undefined
bird mentions --user @username -n 10
undefined

Manage Bookmarks

管理书签

bash
undefined
bash
undefined

List bookmarks

列出书签

bird bookmarks -n 20 bird bookmarks --all --json
bird bookmarks -n 20 bird bookmarks --all --json

From a specific folder

列出特定文件夹中的书签

bird bookmarks --folder-id <id> -n 10
bird bookmarks --folder-id <id> -n 10

Remove a bookmark

移除书签

bird unbookmark <tweet-id-or-url>
undefined
bird unbookmark <tweet-id-or-url>
undefined

Get News and Trending

获取新闻与热门话题

bash
undefined
bash
undefined

AI-curated news

AI精选新闻

bird news --ai-only -n 10
bird news --ai-only -n 10

Sports/Entertainment news

体育/娱乐新闻

bird news --sports -n 15 bird news --entertainment -n 10
bird news --sports -n 15 bird news --entertainment -n 10

Include related tweets

包含相关推文

bird news --with-tweets --tweets-per-item 3 -n 10
bird news --with-tweets --tweets-per-item 3 -n 10

Trending topics

热门话题

bird trending -n 10
undefined
bird trending -n 10
undefined

Post Tweets (use with caution)

发布推文（谨慎使用）

bash
undefined
bash
undefined

Send a tweet

发送推文

bird tweet "hello world"
bird tweet "hello world"

Reply to a tweet

回复推文

bird reply <tweet-id-or-url> "my reply"
undefined
bird reply <tweet-id-or-url> "my reply"
undefined

Process JSON Output

处理JSON输出

Use 
jq
to extract specific fields from JSON output:
bash
undefined
使用
jq
从JSON输出中提取特定字段：
bash
undefined

Get tweet text only

仅获取推文文本

bird read <id> --json | jq -r '.text'
bird read <id> --json | jq -r '.text'

Get user info

获取用户信息

bird user-tweets @user -n 5 --json | jq '.[] | {name: .user.name, handle: .user.screen_name}'
bird user-tweets @user -n 5 --json | jq '.[] | {name: .user.name, handle: .user.screen_name}'

Extract media URLs

提取媒体链接

bird read <id> --json | jq -r '.media[]?.url'
bird read <id> --json | jq -r '.media[]?.url'

Save to file

保存到文件

bird user-tweets @user --all --json > tweets.json
undefined
bird user-tweets @user --all --json > tweets.json
undefined

Authentication

身份验证

Bird uses cookie-based authentication (no API keys required). Use 
--auth-token
/ 
--ct0
to pass cookies directly, or 
--cookie-source
for browser cookies.
Browser cookie sources:
  • Safari, Chrome, or Firefox (macOS)
  • Chromium variants (Arc/Brave/etc): use 
    --chrome-profile-dir
  • Choose the cookie order with 
    --cookie-source
    , and specific Firefox profile with 
    --firefox-profile
  • --cookie-source
    is repeatable: 
    safari|chrome|firefox|all|none
Bird使用基于Cookie的身份验证（无需API密钥）。 可使用
--auth-token
/ 
--ct0
直接传入Cookie，或使用
--cookie-source
从浏览器获取Cookie。
浏览器Cookie来源：
  • Safari、Chrome或Firefox（macOS系统）
  • Chromium衍生浏览器（Arc/Brave等）：使用
    --chrome-profile-dir
    参数
  • 使用
    --cookie-source
    选择Cookie来源顺序，使用
    --firefox-profile
    指定特定Firefox配置文件
  • --cookie-source
    参数可重复使用：可选值为
    safari|chrome|firefox|all|none

Config File

配置文件

Global: 
~/.config/bird/config.json5

Project: 
./.birdrc.json5
Example:
json5
{
  cookieSource: ["chrome"],
  chromeProfileDir: "/path/to/Arc/Profile",
  chromeProfile: "Default",
  firefoxProfile: "default-release",
  cookieTimeoutMs: 10000,
  timeoutMs: 20000,
  quoteDepth: 1
}
Environment variables:
  • BIRD_TIMEOUT_MS
  • BIRD_COOKIE_TIMEOUT_MS
  • BIRD_QUOTE_DEPTH
  • BIRD_QUERY_IDS_CACHE
全局配置：
~/.config/bird/config.json5

项目配置：
./.birdrc.json5
示例：
json5
{
  cookieSource: ["chrome"],
  chromeProfileDir: "/path/to/Arc/Profile",
  chromeProfile: "Default",
  firefoxProfile: "default-release",
  cookieTimeoutMs: 10000,
  timeoutMs: 20000,
  quoteDepth: 1
}
环境变量：
  • BIRD_TIMEOUT_MS
  • BIRD_COOKIE_TIMEOUT_MS
  • BIRD_QUOTE_DEPTH
  • BIRD_QUERY_IDS_CACHE

Important Notes

重要说明

  • Uses undocumented X/Twitter GraphQL API - may break without notice
  • Recommendation: Use for reading only. Tweeting may trigger blocks.
  • Rate limits apply - use 
    --delay <ms>
    to add delays between requests
  • Pagination (when supported): 
    search
    , 
    bookmarks
    , 
    likes
    , 
    following
    , and 
    followers
    require 
    --all
    or 
    --cursor
    with 
    --max-pages
    ; 
    list-timeline
    treats 
    --max-pages
    as 
    --all
  • 使用X/Twitter未公开的GraphQL API - 可能会无预警失效
  • 建议：仅用于查看内容。发布推文可能导致账号被限制
  • 存在调用频率限制 - 使用
    --delay <ms>
    参数在请求间添加延迟
  • 分页功能（支持的场景）：
    search
    、
    bookmarks
    、
    likes
    、
    following
    和
    followers
    需要使用
    --all
    或
    --cursor
    配合
    --max-pages
    参数；
    list-timeline
    将
    --max-pages
    视为
    --all

Troubleshooting

故障排除

Query IDs stale (404 errors):
bash
bird query-ids --fresh
Query IDs cache:
  • Default: 
    ~/.config/bird/query-ids-cache.json
  • Override: 
    BIRD_QUERY_IDS_CACHE=/path/to/file.json
Cookie extraction fails:
  • Confirm you're logged into X/Twitter in the browser
  • Try a different 
    --cookie-source
    order
  • For Arc/Brave, pass 
    --chrome-profile-dir
Auth fails with flags/env:
  • Ensure 
    --auth-token
    and 
    --ct0
    are from the same session
  • Try browser cookies instead of flags for a quick sanity check
查询ID过期（出现404错误）：
bash
bird query-ids --fresh
查询ID缓存：
  • 默认路径：
    ~/.config/bird/query-ids-cache.json
  • 自定义路径：
    BIRD_QUERY_IDS_CACHE=/path/to/file.json
Cookie提取失败：
  • 确认已在浏览器中登录X/Twitter
  • 尝试更换
    --cookie-source
    的顺序
  • 对于Arc/Brave浏览器，需传入
    --chrome-profile-dir
    参数
使用参数/环境变量身份验证失败：
  • 确保
    --auth-token
    和
    --ct0
    来自同一会话
  • 尝试使用浏览器Cookie进行快速验证

Reference

参考文档

See references/commands.md for complete command documentation.
完整命令文档请查看references/commands.md。