Back to Details

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
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 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
int20返回数量（0-50）
--offset
int0偏移量（offset + count < 200）
--owner-ids
string—文件所有者 Open ID（逗号分隔）
--chat-ids
string—文件所在群 ID（逗号分隔）
-o json
string—JSON 格式输出
ParameterTypeDefaultDescription
--docs-types
stringAllFilter by document type (comma-separated, lowercase)
--count
int20Number of results returned (0-50)
--offset
int0Offset (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
快捷方式
TypeDescriptionTypeDescription
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
stringJSON 格式输出
ParameterTypeDescription
--chat-ids
stringLimit to specific group chats (comma-separated)
--from-ids
stringLimit to specific sender IDs (comma-separated)
--at-chatter-ids
stringLimit to specific mentioned user IDs (comma-separated)
--message-type
stringMessage type: 
file
/
image
/
media
--chat-type
stringChat type: 
group_chat
/
p2p_chat
--from-type
stringSender type: 
bot
/
user
--start-time
stringStart time (Unix timestamp in seconds)
--end-time
stringEnd time (Unix timestamp in seconds)
--page-size
intNumber of results per page (default 20)
--page-token
stringPagination token (returned from previous page)
-o json
stringOutput 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
stringJSON 格式输出
ParameterTypeDescription
--page-size
intNumber of results per page (default 20)
--page-token
stringPagination token
-o json
stringOutput 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
技能。
IssueCauseSolution
"Missing User Access Token"Never logged inExecute the two-step login process
"User Access Token has expired"Both access and refresh tokens have expiredLog in again
Permission error 99991679 mentions app searchApp search permission not enabled, or the scope is unavailable in the Developer Admin ConsoleConfirm 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 resultsKeywords do not match or no access to the docsTry broader keywords, or check doc permissions
offset + count exceeds 200Feishu API limitMaximum of 200 results can be retrieved via pagination
For complete authentication flow and Token management, refer to the 
feishu-cli-auth
skill.