bird

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

bird 🐦 — fast X CLI for tweeting, replying, and reading

bird 🐦 — 用于发推、回复、阅读推文的高速X CLI工具

bird

is a fast X CLI for tweeting, replying, and reading via X/Twitter GraphQL (cookie auth).

bird

是一款基于X/Twitter GraphQL（cookie认证）的高速X CLI工具，支持发推、回复、阅读推文。

Disclaimer

免责声明

This project uses X/Twitter’s undocumented web GraphQL API (and cookie auth). X can change endpoints, query IDs, and anti-bot behavior at any time — expect this to break without notice.

Strong recommendation: Do not use bird to tweet. You will hit blocks very quickly. Use it to read tweets. Bots are not welcome on X/Twitter. If you absolutely have to, use browser automation instead, or pay for the Twitter API to create tweets.

本项目使用X/Twitter未公开的Web GraphQL API（以及cookie认证）。X随时可能更改接口、查询ID以及反机器人策略——请预期工具可能在无通知的情况下失效。

强烈建议：不要使用bird发推，你会很快被平台限制。仅将其用于阅读推文。X/Twitter不欢迎机器人。如果你确实需要发推，请改用浏览器自动化工具，或者付费使用Twitter API创建推文。

Install

安装

bash

npm install -g @steipete/bird

bash

npm install -g @steipete/bird

or

或者

pnpm add -g @steipete/bird

or

或者

bun add -g @steipete/bird

one-shot (no install)

单次运行（无需安装）

bunx @steipete/bird whoami


Homebrew (macOS, prebuilt Bun binary):

```bash
brew install steipete/tap/bird

bunx @steipete/bird whoami


Homebrew（macOS，预编译的Bun二进制包）：

```bash
brew install steipete/tap/bird

Quickstart

快速开始

bash

undefined

bash

undefined

Show the logged-in account

展示当前登录的账号

bird whoami

Discover command help

查看命令帮助

bird help whoami

Read a tweet (URL or ID)

阅读推文（支持URL或ID）

bird read https://x.com/user/status/1234567890123456789 bird 1234567890123456789 --json

Thread + replies

主题串+回复

bird thread https://x.com/user/status/1234567890123456789 bird replies 1234567890123456789 bird replies 1234567890123456789 --max-pages 3 --json bird thread 1234567890123456789 --max-pages 3 --json

Search + mentions

搜索+提及

bird search "from:steipete" -n 5 bird mentions -n 5 bird mentions --user @steipete -n 5

User tweets (profile timeline)

用户推文（个人主页时间线）

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

Bookmarks

书签

bird bookmarks -n 5 bird bookmarks --folder-id 123456789123456789 -n 5 # https://x.com/i/bookmarks/<folder-id> bird bookmarks --all --json bird bookmarks --all --max-pages 2 --json bird bookmarks --include-parent --json bird unbookmark 1234567890123456789 bird unbookmark https://x.com/user/status/1234567890123456789

Likes

bird likes -n 5

News and trending topics (AI-curated from Explore tabs)

新闻与热门话题（探索标签页AI精选内容）

bird news --ai-only -n 10 bird news --sports -n 5

Lists

列表

bird list-timeline 1234567890 -n 20 bird list-timeline https://x.com/i/lists/1234567890 --all --json bird list-timeline 1234567890 --max-pages 3 --json

Following (who you follow)

关注列表（你关注的用户）

bird following -n 20 bird following --user 12345678 -n 10 # by user ID

bird following -n 20 bird following --user 12345678 -n 10 # 通过用户ID查询

Followers (who follows you)

粉丝列表（关注你的用户）

bird followers -n 20 bird followers --user 12345678 -n 10 # by user ID

bird followers -n 20 bird followers --user 12345678 -n 10 # 通过用户ID查询

Refresh GraphQL query IDs cache (no rebuild)

刷新GraphQL查询ID缓存（无需重新构建）

bird query-ids --fresh

undefined

bird query-ids --fresh

undefined

News & Trending

新闻与热门话题

Fetch AI-curated news and trending topics from X's Explore page tabs:

bash

undefined

从X的探索页面标签页获取AI精选的新闻和热门话题：

bash

undefined

Fetch 10 news items from all tabs (default: For You, News, Sports, Entertainment)

从所有标签页获取10条新闻（默认：推荐、新闻、体育、娱乐）

bird news -n 10

Fetch only AI-curated news (filters out regular trends)

仅获取AI精选新闻（过滤普通热门内容）

bird news --ai-only -n 20

Fetch from specific tabs

从指定标签页获取内容

bird news --news-only --ai-only -n 10 bird news --sports -n 15 bird news --entertainment --ai-only -n 5

Include related tweets for each news item

包含每条新闻对应的相关推文

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

Combine multiple tab filters

组合多个标签页筛选条件

bird news --sports --entertainment -n 20

JSON output

JSON格式输出

bird news --json -n 5 bird news --json-full --ai-only -n 10 # includes raw API response


Tab options (can be combined):
- `--for-you` — Fetch from For You tab only
- `--news-only` — Fetch from News tab only
- `--sports` — Fetch from Sports tab only
- `--entertainment` — Fetch from Entertainment tab only
- `--trending-only` — Fetch from Trending tab only

By default, the command fetches from For You, News, Sports, and Entertainment tabs (Trending excluded to reduce noise). Headlines are automatically deduplicated across tabs.

bird news --json -n 5 bird news --json-full --ai-only -n 10 # 包含原始API响应


标签页选项（可组合使用）：
- `--for-you` — 仅从推荐标签页获取内容
- `--news-only` — 仅从新闻标签页获取内容
- `--sports` — 仅从体育标签页获取内容
- `--entertainment` — 仅从娱乐标签页获取内容
- `--trending-only` — 仅从热门标签页获取内容

默认情况下，命令会从推荐、新闻、体育、娱乐标签页获取内容（为了减少噪音，排除了热门标签页）。不同标签页的头条内容会自动去重。

Library

作为库使用

bird

can be used as a library (same GraphQL client as the CLI):

import { TwitterClient, resolveCredentials } from '@steipete/bird';

const { cookies } = await resolveCredentials({ cookieSource: 'safari' });
const client = new TwitterClient({ cookies });

// Search for tweets
const searchResult = await client.search('from:steipete', 50);

// Fetch news and trending topics from all tabs (default: For You, News, Sports, Entertainment)
const newsResult = await client.getNews(10, { aiOnly: true });

// Fetch from specific tabs with related tweets
const sportsNews = await client.getNews(10, {
  aiOnly: true,
  withTweets: true,
  tabs: ['sports', 'entertainment']
});

Account details (About profile):

const aboutResult = await client.getUserAboutAccount('steipete');
if (aboutResult.success && aboutResult.aboutProfile) {
  console.log(aboutResult.aboutProfile.accountBasedIn);
}

Fields:

```
accountBasedIn
```
```
source
```
```
createdCountryAccurate
```
```
locationAccurate
```
```
learnMoreUrl
```

bird

可作为库使用（使用和CLI相同的GraphQL客户端）：

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 });

// 从指定标签页获取内容并附带相关推文
const sportsNews = await client.getNews(10, {
  aiOnly: true,
  withTweets: true,
  tabs: ['sports', 'entertainment']
});

账号详情（个人简介）：

const aboutResult = await client.getUserAboutAccount('steipete');
if (aboutResult.success && aboutResult.aboutProfile) {
  console.log(aboutResult.aboutProfile.accountBasedIn);
}

字段说明：

```
accountBasedIn
```
```
source
```
```
createdCountryAccurate
```
```
locationAccurate
```
```
learnMoreUrl
```

Commands

命令列表

```
bird tweet "<text>"
```
— post a new tweet.
```
bird reply <tweet-id-or-url> "<text>"
```
— reply to a tweet using its ID or URL.
```
bird help [command]
```
— show help (or help for a subcommand).
```
bird query-ids [--fresh] [--json]
```
— inspect or refresh cached GraphQL query IDs.

bird home [-n count] [--following] [--json] [--json-full]

— fetch your home timeline (For You) or Following feed.

```
bird read <tweet-id-or-url> [--json]
```
— fetch tweet content as text or JSON.
```
bird <tweet-id-or-url> [--json]
```
— shorthand for
```
read
```
when only a URL or ID is provided.

bird replies <tweet-id-or-url> [--all] [--max-pages n] [--cursor string] [--delay ms] [--json]

— list replies to a tweet.

bird thread <tweet-id-or-url> [--all] [--max-pages n] [--cursor string] [--delay ms] [--json]

— show the full conversation thread.

bird search "<query>" [-n count] [--all] [--max-pages n] [--cursor string] [--json]

— search for tweets matching a query;

--max-pages

requires

--all

--cursor

```
bird mentions [-n count] [--user @handle] [--json]
```
— find tweets mentioning a user (defaults to the authenticated user).

bird user-tweets <@handle> [-n count] [--cursor string] [--max-pages n] [--delay ms] [--json]

— get tweets from a user's profile timeline.

bird bookmarks [-n count] [--folder-id id] [--all] [--max-pages n] [--cursor string] [--expand-root-only] [--author-chain] [--author-only] [--full-chain-only] [--include-ancestor-branches] [--include-parent] [--thread-meta] [--sort-chronological] [--json]

— list your bookmarked tweets (or a specific bookmark folder); expansion flags control thread context;

--max-pages

requires

--all

--cursor

```
bird unbookmark <tweet-id-or-url...>
```
— remove one or more bookmarks by tweet ID or URL.

bird likes [-n count] [--all] [--max-pages n] [--cursor string] [--json] [--json-full]

— list your liked tweets;

--max-pages

requires

--all

--cursor

bird news [-n count] [--ai-only] [--with-tweets] [--tweets-per-item n] [--for-you] [--news-only] [--sports] [--entertainment] [--trending-only] [--json]

— fetch news and trending topics from X's Explore tabs.

```
bird trending
```
— alias for
```
news
```
command.

bird lists [--member-of] [-n count] [--json]

— list your lists (owned or memberships).

bird list-timeline <list-id-or-url> [-n count] [--all] [--max-pages n] [--cursor string] [--json]

— get tweets from a list timeline;

--max-pages

implies

--all

bird following [--user <userId>] [-n count] [--cursor string] [--all] [--max-pages n] [--json]

— list users that you (or another user) follow;

--max-pages

requires

--all

bird followers [--user <userId>] [-n count] [--cursor string] [--all] [--max-pages n] [--json]

— list users that follow you (or another user);

--max-pages

requires

--all

```
bird about <@handle> [--json]
```
— get account origin and location information for a user.
```
bird whoami
```
— print which Twitter account your cookies belong to.
```
bird check
```
— show which credentials are available and where they were sourced from.

Bookmarks flags:

```
--expand-root-only
```
: expand threads only when the bookmark is a root tweet.
```
--author-chain
```
: keep only the bookmarked author's connected self-reply chain.
```
--author-only
```
: include all tweets from the bookmarked author within the thread.
```
--full-chain-only
```
: keep the entire reply chain connected to the bookmarked tweet (all authors).
```
--include-ancestor-branches
```
: include sibling branches for ancestors when using
```
--full-chain-only
```
.
```
--include-parent
```
: include the direct parent tweet for non-root bookmarks.
```
--thread-meta
```
: add thread metadata fields to each tweet.
```
--sort-chronological
```
: sort output globally oldest to newest (default preserves bookmark order).

Global options:

```
--auth-token <token>
```
: set the
```
auth_token
```
cookie manually.
```
--ct0 <token>
```
: set the
```
ct0
```
cookie manually.
```
--cookie-source <safari|chrome|firefox>
```
: choose browser cookie source (repeatable; order matters).
```
--chrome-profile <name>
```
: Chrome profile name for cookie extraction (e.g.,
```
Default
```
,
```
Profile 2
```
).
```
--chrome-profile-dir <path>
```
: Chrome/Chromium profile directory or cookie DB path for cookie extraction.
```
--firefox-profile <name>
```
: Firefox profile for cookie extraction.
```
--cookie-timeout <ms>
```
: cookie extraction timeout for keychain/OS helpers (milliseconds).
```
--timeout <ms>
```
: abort requests after the given timeout (milliseconds).
```
--quote-depth <n>
```
: max quoted tweet depth in JSON output (default: 1; 0 disables).
```
--plain
```
: stable output (no emoji, no color).
```
--no-emoji
```
: disable emoji output.
```
--no-color
```
: disable ANSI colors (or set
```
NO_COLOR=1
```
).
```
--media <path>
```
: attach media file (repeatable, up to 4 images or 1 video).
```
--alt <text>
```
: alt text for the corresponding
```
--media
```
(repeatable).

```
bird tweet "<text>"
```
— 发布新推文。
```
bird reply <tweet-id-or-url> "<text>"
```
— 通过推文ID或URL回复推文。
```
bird help [command]
```
— 显示帮助（或子命令的帮助信息）。
```
bird query-ids [--fresh] [--json]
```
— 查看或刷新缓存的GraphQL查询ID。
```
bird home [-n count] [--following] [--json] [--json-full]
```
— 获取你的首页时间线（推荐）或关注流。
```
bird read <tweet-id-or-url> [--json]
```
— 以文本或JSON格式获取推文内容。
```
bird <tweet-id-or-url> [--json]
```
— 仅提供URL或ID时，是
```
read
```
命令的简写。

bird replies <tweet-id-or-url> [--all] [--max-pages n] [--cursor string] [--delay ms] [--json]

— 列出推文的回复。

bird thread <tweet-id-or-url> [--all] [--max-pages n] [--cursor string] [--delay ms] [--json]

— 展示完整的对话主题串。

bird search "<query>" [-n count] [--all] [--max-pages n] [--cursor string] [--json]

— 搜索匹配查询条件的推文；

--max-pages

需要搭配

--all

或

--cursor

使用。

```
bird mentions [-n count] [--user @handle] [--json]
```
— 查找提及某个用户的推文（默认是当前登录用户）。

bird user-tweets <@handle> [-n count] [--cursor string] [--max-pages n] [--delay ms] [--json]

— 获取用户个人主页时间线的推文。

bird bookmarks [-n count] [--folder-id id] [--all] [--max-pages n] [--cursor string] [--expand-root-only] [--author-chain] [--author-only] [--full-chain-only] [--include-ancestor-branches] [--include-parent] [--thread-meta] [--sort-chronological] [--json]

— 列出你收藏的推文（或指定书签文件夹的内容）；扩展标志控制主题串上下文；

--max-pages

需要搭配

--all

或

--cursor

使用。

```
bird unbookmark <tweet-id-or-url...>
```
— 通过推文ID或URL移除一个或多个书签。

bird likes [-n count] [--all] [--max-pages n] [--cursor string] [--json] [--json-full]

— 列出你点赞的推文；

--max-pages

需要搭配

--all

或

--cursor

使用。

bird news [-n count] [--ai-only] [--with-tweets] [--tweets-per-item n] [--for-you] [--news-only] [--sports] [--entertainment] [--trending-only] [--json]

— 从X的探索标签页获取新闻和热门话题。

```
bird trending
```
—
```
news
```
命令的别名。
```
bird lists [--member-of] [-n count] [--json]
```
— 列出你的列表（你创建的或你加入的）。

bird list-timeline <list-id-or-url> [-n count] [--all] [--max-pages n] [--cursor string] [--json]

— 获取列表时间线的推文；

--max-pages

默认开启

--all

。

bird following [--user <userId>] [-n count] [--cursor string] [--all] [--max-pages n] [--json]

— 列出你（或其他用户）关注的用户；

--max-pages

需要搭配

--all

使用。

bird followers [--user <userId>] [-n count] [--cursor string] [--all] [--max-pages n] [--json]

— 列出关注你（或其他用户）的用户；

--max-pages

需要搭配

--all

使用。

```
bird about <@handle> [--json]
```
— 获取用户的账号注册地和位置信息。
```
bird whoami
```
— 打印你的cookie对应的Twitter账号。
```
bird check
```
— 展示可用的凭证以及它们的来源。

书签定参数说明：

```
--expand-root-only
```
: 仅当书签是根推文时才展开主题串。
```
--author-chain
```
: 仅保留书签作者的连续自回复串。
```
--author-only
```
: 包含主题串中书签作者发布的所有推文。
```
--full-chain-only
```
: 保留和书签推文关联的完整回复串（所有作者）。
```
--include-ancestor-branches
```
: 使用
```
--full-chain-only
```
时包含祖先推文的兄弟分支。
```
--include-parent
```
: 非根书签包含直接父推文。
```
--thread-meta
```
: 为每条推文添加主题串元数据字段。
```
--sort-chronological
```
: 全局按时间从旧到新排序（默认保留书签排序顺序）。

全局选项：

```
--auth-token <token>
```
: 手动设置
```
auth_token
```
cookie。
```
--ct0 <token>
```
: 手动设置
```
ct0
```
cookie。
```
--cookie-source <safari|chrome|firefox>
```
: 选择浏览器cookie来源（可重复设置，顺序优先）。
```
--chrome-profile <name>
```
: 用于提取cookie的Chrome配置文件名称（例如
```
Default
```
、
```
Profile 2
```
）。
```
--chrome-profile-dir <path>
```
: 用于提取cookie的Chrome/Chromium配置文件目录或cookie数据库路径。
```
--firefox-profile <name>
```
: 用于提取cookie的Firefox配置文件。
```
--cookie-timeout <ms>
```
: 钥匙串/系统工具提取cookie的超时时间（毫秒）。
```
--timeout <ms>
```
: 请求超时时间，超过后终止请求（毫秒）。
```
--quote-depth <n>
```
: JSON输出中引用推文的最大深度（默认：1；0表示禁用）。
```
--plain
```
: 稳定输出（无emoji、无颜色）。
```
--no-emoji
```
: 禁用emoji输出。
```
--no-color
```
: 禁用ANSI颜色（或设置
```
NO_COLOR=1
```
）。
```
--media <path>
```
: 附加媒体文件（可重复设置，最多4张图片或1个视频）。
```
--alt <text>
```
: 对应
```
--media
```
的替代文本（可重复设置）。

Authentication (GraphQL)

认证（GraphQL）

GraphQL mode uses your existing X/Twitter web session (no password prompt). It sends requests to internal X endpoints and authenticates via cookies (

auth_token

ct0

Write operations:

```
tweet
```
/
```
reply
```
primarily use GraphQL (
```
CreateTweet
```
).
If GraphQL returns error
```
226
```
(“automated request”),
```
bird
```
falls back to the legacy
```
statuses/update.json
```
endpoint.

bird

resolves credentials in this order:

CLI flags:
```
--auth-token
```
,
```
--ct0
```

Environment variables:

AUTH_TOKEN

CT0

(fallback:

TWITTER_AUTH_TOKEN

TWITTER_CT0

)

Browser cookies via
```
@steipete/sweet-cookie
```
(override via
```
--cookie-source
```
order)

Browser cookie sources:

Safari:

~/Library/Cookies/Cookies.binarycookies

(fallback:

~/Library/Containers/com.apple.Safari/Data/Library/Cookies/Cookies.binarycookies

)

Chrome:

~/Library/Application Support/Google/Chrome/<Profile>/Cookies

Firefox:

~/Library/Application Support/Firefox/Profiles/<profile>/cookies.sqlite

For Chromium variants (Arc/Brave/etc), pass a profile directory or cookie DB via
```
--chrome-profile-dir
```
.

GraphQL模式使用你现有的X/Twitter Web会话（无需输入密码）。它会向X的内部接口发送请求，并通过cookie（

auth_token

、

ct0

）进行认证。

写操作：

```
tweet
```
/
```
reply
```
主要使用GraphQL（
```
CreateTweet
```
）。
如果GraphQL返回错误
```
226
```
（“自动化请求”），
```
bird
```
会回退到旧版
```
statuses/update.json
```
接口。

bird

按以下顺序解析凭证：

CLI参数：
```
--auth-token
```
、
```
--ct0
```

环境变量：

AUTH_TOKEN

、

CT0

（备选：

TWITTER_AUTH_TOKEN

、

TWITTER_CT0

）

通过
```
@steipete/sweet-cookie
```
读取浏览器cookie（可通过
```
--cookie-source
```
顺序覆盖）

浏览器cookie来源：

Safari:

~/Library/Cookies/Cookies.binarycookies

（备选：

~/Library/Containers/com.apple.Safari/Data/Library/Cookies/Cookies.binarycookies

）

Chrome:

~/Library/Application Support/Google/Chrome/<Profile>/Cookies

Firefox:
```
~/Library/Application Support/Firefox/Profiles/<profile>/cookies.sqlite
```
- 对于Chromium衍生浏览器（Arc/Brave等），通过
```
--chrome-profile-dir
```
  传入配置文件目录或cookie数据库路径。

Config (JSON5)

配置（JSON5）

Config precedence: CLI flags > env vars > project config > global config.

Global:
```
~/.config/bird/config.json5
```
Project:
```
./.birdrc.json5
```

Example

~/.config/bird/config.json5

json5

{
  // Cookie source order for browser extraction (string or array)
  cookieSource: ["firefox", "safari"],
  chromeProfileDir: "/path/to/Chromium/Profile",
  firefoxProfile: "default-release",
  cookieTimeoutMs: 30000,
  timeoutMs: 20000,
  quoteDepth: 1
}

Environment shortcuts:

```
BIRD_TIMEOUT_MS
```
```
BIRD_COOKIE_TIMEOUT_MS
```
```
BIRD_QUOTE_DEPTH
```

配置优先级：CLI参数 > 环境变量 > 项目配置 > 全局配置。

全局配置：
```
~/.config/bird/config.json5
```
项目配置：
```
./.birdrc.json5
```

示例

~/.config/bird/config.json5

：

json5

{
  // 浏览器提取cookie的来源顺序（字符串或数组）
  cookieSource: ["firefox", "safari"],
  chromeProfileDir: "/path/to/Chromium/Profile",
  firefoxProfile: "default-release",
  cookieTimeoutMs: 30000,
  timeoutMs: 20000,
  quoteDepth: 1
}

环境变量快捷方式：

```
BIRD_TIMEOUT_MS
```
```
BIRD_COOKIE_TIMEOUT_MS
```
```
BIRD_QUOTE_DEPTH
```

Output

输出

```
--json
```
prints raw tweet objects for read/replies/thread/search/mentions/user-tweets/bookmarks/likes.

When using

--json

with pagination (

--all

--cursor

--max-pages

, or for

user-tweets

when

-n > 20

), output is

{ tweets, nextCursor }

```
read
```
returns full text for Notes and Articles when present.
Use
```
--plain
```
for stable, script-friendly output (no emoji, no color).

```
--json
```
会为read/replies/thread/search/mentions/user-tweets/bookmarks/likes等命令打印原始推文对象。
当
```
--json
```
搭配分页参数（
```
--all
```
、
```
--cursor
```
、
```
--max-pages
```
，或
```
user-tweets
```
的
```
-n > 20
```
）使用时，输出格式为
```
{ tweets, nextCursor }
```
。
如果存在笔记和长文内容，
```
read
```
会返回完整文本。
使用
```
--plain
```
获取稳定的、适合脚本处理的输出（无emoji、无颜色）。

JSON Schema

When using

--json

, tweet objects include:

Field	Type	Description
`id`	string	Tweet ID
`text`	string	Full tweet text (includes Note/Article content when present)
`author`	object	`{ username, name }`
`authorId`	string?	Author's user ID
`createdAt`	string	Timestamp
`replyCount`	number	Number of replies
`retweetCount`	number	Number of retweets
`likeCount`	number	Number of likes
`conversationId`	string	Thread conversation ID
`inReplyToStatusId`	string?	Parent tweet ID (present if this is a reply)
`quotedTweet`	object?	Embedded quote tweet (same schema; depth controlled by `--quote-depth` )

When using

--json

with

following

followers

, user objects include:

Field	Type	Description
`id`	string	User ID
`username`	string	Username/handle
`name`	string	Display name
`description`	string?	User bio
`followersCount`	number?	Followers count
`followingCount`	number?	Following count
`isBlueVerified`	boolean?	Blue verified flag
`profileImageUrl`	string?	Profile image URL
`createdAt`	string?	Account creation timestamp

When using

--json

with

news

trending

, news objects include:

Field	Type	Description
`id`	string	Unique identifier for the news item
`headline`	string	News headline or trend title
`category`	string?	Category (e.g., "AI · Technology", "Trending", "News")
`timeAgo`	string?	Relative time (e.g., "2h ago")
`postCount`	number?	Number of posts
`description`	string?	Item description
`url`	string?	URL to the trend or news article
`tweets`	array?	Related tweets (only when `--with-tweets` is used)
`_raw`	object?	Raw API response (only when `--json-full` is used)

使用

--json

时，推文对象包含以下字段：

字段	类型	描述
`id`	string	推文ID
`text`	string	完整推文文本（存在笔记/长文时包含对应内容）
`author`	object	`{ username, name }`
`authorId`	string?	作者用户ID
`createdAt`	string	时间戳
`replyCount`	number	回复数量
`retweetCount`	number	转发数量
`likeCount`	number	点赞数量
`conversationId`	string	主题串会话ID
`inReplyToStatusId`	string?	父推文ID（仅回复类推文存在）
`quotedTweet`	object?	内嵌引用推文（相同Schema；深度由 `--quote-depth` 控制）

在

following

followers

命令中使用

--json

时，用户对象包含以下字段：

字段	类型	描述
`id`	string	用户ID
`username`	string	用户名/账号
`name`	string	展示名称
`description`	string?	用户简介
`followersCount`	number?	粉丝数量
`followingCount`	number?	关注数量
`isBlueVerified`	boolean?	蓝V认证标记
`profileImageUrl`	string?	头像URL
`createdAt`	string?	账号创建时间戳

在

news

trending

命令中使用

--json

时，新闻对象包含以下字段：

字段	类型	描述
`id`	string	新闻条目的唯一标识
`headline`	string	新闻头条或热门话题标题
`category`	string?	分类（例如"AI · Technology"、"Trending"、"News"）
`timeAgo`	string?	相对时间（例如"2h ago"）
`postCount`	number?	帖子数量
`description`	string?	条目描述
`url`	string?	热门话题或新闻文章的URL
`tweets`	array?	相关推文（仅使用 `--with-tweets` 时存在）
`_raw`	object?	原始API响应（仅使用 `--json-full` 时存在）

Query IDs (GraphQL)

查询ID（GraphQL）

X rotates GraphQL “query IDs” frequently. Each GraphQL operation is addressed as:

```
operationName
```
(e.g.
```
TweetDetail
```
,
```
CreateTweet
```
)
```
queryId
```
(rotating ID baked into X’s web client bundles)

bird

ships with a baseline mapping in

src/lib/query-ids.json

(copied into

dist/

on build). At runtime, it can refresh that mapping by scraping X’s public web client bundles and caching the result on disk.

Runtime cache:

Default path:
```
~/.config/bird/query-ids-cache.json
```
Override path:
```
BIRD_QUERY_IDS_CACHE=/path/to/file.json
```
TTL: 24h (stale cache is still used, but marked “not fresh”)

Auto-recovery:

On GraphQL
```
404
```
(query ID invalid),
```
bird
```
forces a refresh once and retries.
For
```
TweetDetail
```
/
```
SearchTimeline
```
,
```
bird
```
also rotates through a small set of known fallback IDs to reduce breakage while refreshing.

Refresh on demand:

bash

bird query-ids --fresh

Exit codes:

```
0
```
: success
```
1
```
: runtime error (network/auth/etc)
```
2
```
: invalid usage/validation (e.g. bad
```
--user
```
handle)

X会频繁轮换GraphQL“查询ID”。每个GraphQL操作的寻址方式为：

```
operationName
```
（例如
```
TweetDetail
```
、
```
CreateTweet
```
）
```
queryId
```
（X的Web客户端包中内置的轮换ID）

bird

在

src/lib/query-ids.json

中内置了基础映射表（构建时会复制到

dist/

目录）。运行时，它可以通过爬取X的公开Web客户端包刷新映射表，并将结果缓存到磁盘。

运行时缓存：

默认路径：
```
~/.config/bird/query-ids-cache.json
```
覆盖路径：
```
BIRD_QUERY_IDS_CACHE=/path/to/file.json
```
有效期：24小时（过期缓存仍会被使用，但会标记为“非新鲜”）

自动恢复：

遇到GraphQL
```
404
```
（查询ID无效）时，
```
bird
```
会强制刷新一次并重试。
对于
```
TweetDetail
```
/
```
SearchTimeline
```
，
```
bird
```
还会轮换使用一小部分已知的备用ID，减少刷新期间的失效情况。

按需刷新：

bash

bird query-ids --fresh

退出码：

```
0
```
: 成功
```
1
```
: 运行时错误（网络/认证等）
```
2
```
: 无效使用/校验失败（例如错误的
```
--user
```
账号）

Version

版本

bird --version

prints

package.json

version plus current git sha when available, e.g.

0.3.0 (3df7969b)

bird --version

会打印

package.json

的版本号以及可用的当前git sha，例如

0.3.0 (3df7969b)

。

Media uploads

媒体上传

Attach media with
```
--media
```
(repeatable) and optional
```
--alt
```
per item.
Up to 4 images/GIFs, or 1 video (no mixing). Supported: jpg, jpeg, png, webp, gif, mp4, mov.
Images/GIFs + 1 video supported (uploads via Twitter legacy upload endpoint + cookies; video may take longer to process).

Example:

bash

bird tweet "hi" --media img.png --alt "desc"

使用
```
--media
```
附加媒体（可重复设置），每个媒体可选择性搭配
```
--alt
```
设置替代文本。
最多支持4张图片/GIF，或1个视频（不可混合）。支持格式：jpg、jpeg、png、webp、gif、mp4、mov。
支持图片/GIF+1个视频的组合（通过Twitter旧版上传接口+cookie上传；视频处理可能需要更长时间）。

示例：

bash

bird tweet "hi" --media img.png --alt "desc"