feishu-cli-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

飞书搜索

Feishu Search

搜索飞书云文档、消息和应用。所有搜索命令必须使用 User Access Token。

Search Feishu cloud docs, messages, and apps. All search commands must use a User Access Token.

执行流程

Execution Flow

每次执行搜索前，按以下流程操作：

Follow the below steps before performing any search:

1. 检查 Token 状态

1. Check Token Status

bash

feishu-cli auth status -o json

根据返回结果判断：

```
logged_in=false
```
→ 需要登录（步骤 2）
```
access_token_valid=true
```
+ scope 包含所需权限 → 直接搜索（步骤 3）

access_token_valid=false

refresh_token_valid=true

→ 无需操作，下次搜索时自动刷新

access_token_valid=false

refresh_token_valid=false

→ 需要重新登录（步骤 2）

scope 缺少所需权限 → 需要重新登录并补充 scope（步骤 2）

bash

feishu-cli auth status -o json

Judge based on the returned results:

```
logged_in=false
```
→ Need to log in (Step 2)
```
access_token_valid=true
```
+ scope includes required permissions → Proceed to search directly (Step 3)
```
access_token_valid=false
```
+
```
refresh_token_valid=true
```
→ No action needed, token will be automatically refreshed during next search

access_token_valid=false

refresh_token_valid=false

→ Need to log in again (Step 2)

Required permissions missing from scope → Need to log in again and add the required scope (Step 2)

2. 登录获取 Token（如需要）

2. Log in to Get Token (if needed)

使用两步式非交互登录，始终使用最大 scope 范围（覆盖搜索 + wiki + 日历 + 任务等全部功能）：

bash

undefined

Use two-step non-interactive login, always use the maximum scope range (covers all functions including search + wiki + calendar + tasks, etc.):

bash

undefined

步骤 A：生成授权 URL（最大 scope）

Step A: Generate authorization URL (maximum scope)

feishu-cli auth login --print-url --scopes
"offline_access
search:docs:read search:message drive:drive.search:readonly
wiki:wiki:readonly
calendar:calendar:read calendar:calendar.event:read
calendar:calendar.event:create calendar:calendar.event:update
calendar:calendar.event:reply calendar:calendar.free_busy:read
task:task:read task:task:write
task:tasklist:read task:tasklist:write
im:message:readonly im:message.group_msg:get_as_user im:chat:read contact:user.base:readonly
drive:drive.metadata:readonly"


> **scope 命名说明**：飞书 OAuth scope 命名不完全统一，`search:docs:read` 带 `:read` 后缀，而 `search:message` 不带。这是飞书平台定义，非笔误。

将输出的 `auth_url` 展示给用户，请用户在浏览器中完成授权。授权后浏览器跳转到无法访问的页面，让用户复制地址栏完整 URL。

```bash


> **Scope Naming Note**: Feishu OAuth scope naming is not fully consistent. `search:docs:read` has the `:read` suffix, while `search:message` does not. This is defined by the Feishu platform and not a typo.

Show the output `auth_url` to the user and ask them to complete authorization in a browser. After authorization, the browser will redirect to an inaccessible page; ask the user to copy the full URL from the address bar.

```bash

步骤 B：用回调 URL 换 Token

Step B: Exchange callback URL for Token

feishu-cli auth callback "<用户提供的回调URL>" --state "<步骤A输出的state>"

undefined

feishu-cli auth callback "<Callback URL provided by user>" --state "<state output from Step A>"

undefined

3. 执行搜索

3. Perform Search

登录后所有搜索命令自动从

~/.feishu-cli/token.json

读取 Token，无需手动传递。

After login, all search commands will automatically read the Token from

~/.feishu-cli/token.json

; no manual passing is required.

搜索云文档

Search Cloud Docs

搜索当前用户有权访问的飞书云文档和 Wiki。scope:
search:docs:read

bash

feishu-cli search docs "关键词" [选项]

Search Feishu cloud docs and Wiki accessible to the current user. Scope:
search:docs:read

bash

feishu-cli search docs "keywords" [options]

选项

Options

参数	类型	默认值	说明
`--docs-types`	string	全部	文档类型过滤（逗号分隔，小写）
`--count`	int	20	返回数量（0-50）
`--offset`	int	0	偏移量（offset + count < 200）
`--owner-ids`	string	—	文件所有者 Open ID（逗号分隔）
`--chat-ids`	string	—	文件所在群 ID（逗号分隔）
`-o json`	string	—	JSON 格式输出

Parameter	Type	Default	Description
`--docs-types`	string	All	Filter by document type (comma-separated, lowercase)
`--count`	int	20	Number of results returned (0-50)
`--offset`	int	0	Offset (offset + count < 200)
`--owner-ids`	string	—	Open ID of file owner (comma-separated)
`--chat-ids`	string	—	Group ID where the file is located (comma-separated)
`-o json`	string	—	Output in JSON format

文档类型（小写）

Document Types (lowercase)

类型	说明	类型	说明
`doc`	旧版文档	`docx`	新版文档
`sheet`	电子表格	`slides`	幻灯片
`bitable`	多维表格	`mindnote`	思维笔记
`file`	文件	`wiki`	知识库文档
`shortcut`	快捷方式

Type	Description	Type	Description
`doc`	Legacy doc	`docx`	New version doc
`sheet`	Spreadsheet	`slides`	Slides
`bitable`	Base (multi-dimensional table)	`mindnote`	Mind note
`file`	File	`wiki`	Wiki doc
`shortcut`	Shortcut

示例

Examples

bash

undefined

bash

undefined

基础搜索

Basic search

feishu-cli search docs "产品需求"

feishu-cli search docs "product requirements"

只搜索新版文档和 Wiki

Search only new version docs and Wiki

feishu-cli search docs "技术方案" --docs-types docx,wiki

feishu-cli search docs "technical solution" --docs-types docx,wiki

搜索电子表格

Search spreadsheets

feishu-cli search docs "数据报表" --docs-types sheet

feishu-cli search docs "data report" --docs-types sheet

分页获取更多

Get more results with pagination

feishu-cli search docs "季度报告" --count 50

feishu-cli search docs "quarterly report" --count 50

分页查询：获取第一页（20 条）

Pagination query: Get first page (20 results)

feishu-cli search docs "季度报告" --count 20 --offset 0

feishu-cli search docs "quarterly report" --count 20 --offset 0

分页查询：获取第二页

Pagination query: Get second page

feishu-cli search docs "季度报告" --count 20 --offset 20

feishu-cli search docs "quarterly report" --count 20 --offset 20

JSON 格式输出（适合程序解析）

Output in JSON format (suitable for program parsing)

feishu-cli search docs "产品需求" -o json

undefined

feishu-cli search docs "product requirements" -o json

undefined

JSON 输出格式

JSON Output Format

json

{
  "Total": 35367,
  "HasMore": true,
  "ResUnits": [
    {
      "DocsToken": "C29IdflghosjksxWKvNutR3UsXe",
      "DocsType": "docx",
      "Title": "产品需求文档 - Q2",
      "OwnerID": "ou_46bb48e13f9ff5cfd4b60edae00678cd",
      "URL": "https://feishu.cn/docx/C29IdflghosjksxWKvNutR3UsXe"
    }
  ]
}

DocsToken

可以直接用于

feishu-cli doc get

、

doc export

等文档操作命令。

json

{
  "Total": 35367,
  "HasMore": true,
  "ResUnits": [
    {
      "DocsToken": "C29IdflghosjksxWKvNutR3UsXe",
      "DocsType": "docx",
      "Title": "Product Requirements Document - Q2",
      "OwnerID": "ou_46bb48e13f9ff5cfd4b60edae00678cd",
      "URL": "https://feishu.cn/docx/C29IdflghosjksxWKvNutR3UsXe"
    }
  ]
}

DocsToken

can be directly used in document operation commands like

feishu-cli doc get

and

doc export

搜索消息

Search Messages

搜索飞书消息记录。scope:
search:message

bash

feishu-cli search messages "关键词" [选项]

Search Feishu message records. Scope:
search:message

bash

feishu-cli search messages "keywords" [options]

选项

Options

参数	类型	说明
`--chat-ids`	string	限定群聊范围（逗号分隔）
`--from-ids`	string	限定发送者 ID（逗号分隔）
`--at-chatter-ids`	string	限定被@的用户 ID（逗号分隔）
`--message-type`	string	消息类型： `file` / `image` / `media`
`--chat-type`	string	会话类型： `group_chat` / `p2p_chat`
`--from-type`	string	发送者类型： `bot` / `user`
`--start-time`	string	起始时间（Unix 秒级时间戳）
`--end-time`	string	结束时间（Unix 秒级时间戳）
`--page-size`	int	每页数量（默认 20）
`--page-token`	string	分页 token（上一页返回）
`-o json`	string	JSON 格式输出

Parameter	Type	Description
`--chat-ids`	string	Limit to specific group chats (comma-separated)
`--from-ids`	string	Limit to specific sender IDs (comma-separated)
`--at-chatter-ids`	string	Limit to specific mentioned user IDs (comma-separated)
`--message-type`	string	Message type: `file` / `image` / `media`
`--chat-type`	string	Chat type: `group_chat` / `p2p_chat`
`--from-type`	string	Sender type: `bot` / `user`
`--start-time`	string	Start time (Unix timestamp in seconds)
`--end-time`	string	End time (Unix timestamp in seconds)
`--page-size`	int	Number of results per page (default 20)
`--page-token`	string	Pagination token (returned from previous page)
`-o json`	string	Output in JSON format

示例

Examples

bash

undefined

bash

undefined

搜索消息

Search messages

feishu-cli search messages "上线"

feishu-cli search messages "launch"

搜索私聊消息（search-chats 无法搜到 p2p 会话，用此方式替代）

Search private chat messages (search-chats cannot find p2p sessions, use this instead)

feishu-cli search messages "你好" --chat-type p2p_chat

feishu-cli search messages "hello" --chat-type p2p_chat

搜索群聊中的文件消息

Search file messages in group chats

feishu-cli search messages "周报" --chat-type group_chat --message-type file

feishu-cli search messages "weekly report" --chat-type group_chat --message-type file

搜索机器人消息

Search bot messages

feishu-cli search messages "告警" --from-type bot

feishu-cli search messages "alert" --from-type bot

限定时间范围

Limit to time range

feishu-cli search messages "项目" --start-time 1704067200 --end-time 1704153600

feishu-cli search messages "project" --start-time 1704067200 --end-time 1704153600

限定特定群

Limit to specific groups

feishu-cli search messages "会议" --chat-ids oc_xxx,oc_yyy


> **提示**：搜索群聊 API（`search-chats`）**无法搜到 p2p 私聊会话**。要查找私聊内容，使用 `search messages --chat-type p2p_chat`。

feishu-cli search messages "meeting" --chat-ids oc_xxx,oc_yyy


> **Note**: The group chat search API (`search-chats`) **cannot find p2p private sessions**. To find private chat content, use `search messages --chat-type p2p_chat`.

JSON 输出格式

JSON Output Format

json

{
  "MessageIDs": ["om_xxx", "om_yyy"],
  "PageToken": "ea9dcb2f...",
  "HasMore": true
}

返回的

MessageIDs

可用

feishu-cli msg get <message_id>

获取消息详情。

json

{
  "MessageIDs": ["om_xxx", "om_yyy"],
  "PageToken": "ea9dcb2f...",
  "HasMore": true
}

The returned

MessageIDs

can be used with

feishu-cli msg get <message_id>

to retrieve message details.

搜索应用

Search Apps

搜索飞书应用。注意：搜索应用的 scope 需在飞书开发者后台确认是否可用，部分应用可能未开通此权限。

bash

feishu-cli search apps "关键词" [选项]

Search Feishu apps. Note: Confirm if the app search scope is available in the Feishu Developer Admin Console; this permission may not be enabled for some apps.

bash

feishu-cli search apps "keywords" [options]

选项

Options

参数	类型	说明
`--page-size`	int	每页数量（默认 20）
`--page-token`	string	分页 token
`-o json`	string	JSON 格式输出

Parameter	Type	Description
`--page-size`	int	Number of results per page (default 20)
`--page-token`	string	Pagination token
`-o json`	string	Output in JSON format

示例

Examples

bash

feishu-cli search apps "审批"
feishu-cli search apps "OKR" --page-size 50

bash

feishu-cli search apps "approval"
feishu-cli search apps "OKR" --page-size 50

常见问题

Frequently Asked Questions

问题	原因	解决
"缺少 User Access Token"	从未登录	执行两步式登录流程
"User Access Token 已过期"	access + refresh token 都过期	重新登录
99991679 权限错误提到搜索应用	应用未开通搜索应用权限，或该 scope 在开发者后台不可用	在飞书开发者后台确认是否已开通对应权限
99991679 权限错误提到 `search:docs:read`	登录时未包含 `search:docs:read` scope	重新登录，scope 加上 `search:docs:read`
搜索结果为空	关键词不匹配或无权限文档	尝试更宽泛的关键词，或检查文档权限
offset + count 超过 200	飞书 API 限制	最多翻到第 200 条结果

完整的认证流程和 Token 管理请参考
feishu-cli-auth
技能。

Issue	Cause	Solution
"Missing User Access Token"	Never logged in	Execute the two-step login process
"User Access Token has expired"	Both access and refresh tokens have expired	Log in again
Permission error 99991679 mentions app search	App search permission not enabled, or the scope is unavailable in the Developer Admin Console	Confirm if the corresponding permission is enabled in the Feishu Developer Admin Console
Permission error 99991679 mentions `search:docs:read`	`search:docs:read` scope was not included during login	Log in again and add the `search:docs:read` scope
No search results	Keywords do not match or no access to the docs	Try broader keywords, or check doc permissions
offset + count exceeds 200	Feishu API limit	Maximum of 200 results can be retrieved via pagination

For complete authentication flow and Token management, refer to the
feishu-cli-auth
skill.