feishu-cli-search

Feishu Search

Search Feishu cloud documents, messages, and apps. All search commandsmust use a User Access Token。

feishu-cli: if not yet installed, go to riba2534/feishu-cli to get the installation method.

Execution Flow

Before each search execution, follow this flow:

1. Pre-check scope (recommended for AI Agents)

feishu-cli auth check --scope "search:docs:read"
# 或同时检查多个（含搜索应用）
feishu-cli auth check --scope "search:docs:read search:message search:app"

Judge based on the returned result:

• ok=true → execute the search directly (step 3)
• error=not_logged_in or error=token_expired → log in (step 2)
• missing=[...] non-empty → first enable the missing scopes for the app on the Feishu Open Platform (see step 2), then log in again

2. Log in to obtain a Token (if needed)

This project uses Device Flow (RFC 8628) authorization, no redirect URL configuration is required. AI Agents are recommended to use background blocking mode:

# 后台启动（Claude Code 的 run_in_background=true）
feishu-cli auth login --scope "search:docs:read search:message" --json

The first line of stdout outputs {"event":"device_authorization","verification_uri_complete":"...","user_code":"...","expires_in":240,...}. Show verification_uri_complete to the user; after the user completes authorization in the browser, the background process exits automatically, and the second line of stdout outputs {"event":"authorization_complete",...}。

If auth check returns missing=[...], it means the app has not yet enabled the required permissions.feishu-cli does not automate permission requests—guide the user to go to the Feishu Open Platform themselves:

1. Open the Feishu Open Platform → your app → permission management page
2. Search for and enable the missing scopes (for example search:docs:read、search:message), or copy the complete JSON from the README to import all at once
3. Wait for tenant admin approval (if needed)
4. After approval, execute feishu-cli auth login --scope "search:docs:read search:message" --json

For detailed AI Agent authorization conventions, see the feishu-cli-auth skill.

3. Execute the search

After logging in, all search commands automatically read the Token from ~/.feishu-cli/token.json , no manual passing required.

---

Search cloud documents

Search Feishu cloud documents and Wiki that the current user has permission to access.scope: search:docs:read

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

Options

Parameter	Type	Default	Description
--docs-types	string	All	Document type filter (comma-separated, lowercase)
--count	int	20	Number of results to return (0-50)
--offset	int	0	Offset (offset + count < 200)
--owner-ids	string	—	File owner Open ID (comma-separated)
--chat-ids	string	—	ID of the group the file belongs to (comma-separated)
-o json	string	—	JSON format output

Document types (lowercase)

Type	Description	Type	Description
doc	Legacy document	docx	New document
sheet	Spreadsheet	slides	Slides
bitable	Base	mindnote	Mind notes
file	File	wiki	Wiki document
shortcut	Shortcut

Examples

# 基础搜索
feishu-cli search docs "产品需求"

# 只搜索新版文档和 Wiki
feishu-cli search docs "技术方案" --docs-types docx,wiki

# 搜索电子表格
feishu-cli search docs "数据报表" --docs-types sheet

# 分页获取更多
feishu-cli search docs "季度报告" --count 50

# 分页查询：获取第一页（20 条）
feishu-cli search docs "季度报告" --count 20 --offset 0
# 分页查询：获取第二页
feishu-cli search docs "季度报告" --count 20 --offset 20

# JSON 格式输出（适合程序解析）
feishu-cli search docs "产品需求" -o json

v1 vs v2: when to use drive search？

search docs(v1, this section) uses /open-apis/suite/docs-api/search/object, filter is simple (owner_ids / chat_ids / docs_types). drive search(v2, see feishu-cli-drive skill §9) use /open-apis/search/v2/doc_wiki/search, supporting a more granular flat filter:

• --folder-tokens restrict to cloud drive folder (mutually exclusive with --space-ids )
• --space-ids restrict to knowledge base space
• --creator-ids / --sharer-ids multi-user fan-out
• --only-title / --only-comment dimension restriction
• --sort sort (edit_time / open_time / create_time / default)

Both require search:docs:read, choose as needed: use v1 for coarse filtering, v2 for fine filtering.

JSON output format

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

DocsToken can be used directly for feishu-cli doc get、doc export and other document operation commands.

---

Search messages

Search Feishu message records.scope: search:message

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

Options

Parameter	Type	Description
--chat-ids	string	Restrict to chat range (comma-separated)
--from-ids	string	Restrict to sender IDs (comma-separated)
--at-chatter-ids	string	Restrict to 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 per page (default 20)
--page-token	string	Pagination token (returned by previous page)
--page-all	bool	Auto-paginate to fetch all (limited by --page-limit )
--page-limit	int	Max pages for auto-pagination,0=unlimited (default 0); use with --page-all to prevent runaway
--enrich	bool	Enrich content/sender/chat name/time (opt-in, extra API calls)
--card-content-type	string	interactive card enrichment format:user(default, extract card_texts）/ raw(platform-internal full cardDSL) / rendered(OAPI rendered version/fallback version).Only takes effect when --enrich is set, ignored on non-enrich paths
--format	string	Structured output:json/pretty/table/ndjson/csv
--jq	string	Filter structured output with a jq expression
--user-id-type	string	User ID type:open_id(default)/union_id/user_id
-o json	string	JSON format output (equivalent to --format json）

--page-all truncated without notice: only in non-pagination mode (!--page-all and HasMore=true) will print "more results available". When --page-all stops early due to reaching --page-limit (rather than being truly exhausted), the CLI will notindicate that results are truncated—when you need to fetch the full set, set --page-limit to 0, or use the JSON output's HasMore to judge for yourself.

Default vs --enrich: by default only message IDs are returned (-o json outputs {MessageIDs,HasMore,PageToken}), consistent with historical behavior and backward compatible. Adding --enrich will make extra calls to BatchGetMessages and other APIs to enrich content/sender/chat name/time,-o json in which case it returns the enriched array.

Example

# 搜索消息（默认返回消息 ID）
feishu-cli search messages "上线"

# 富化：补全内容/发送者/群名/时间
feishu-cli search messages "上线" --enrich
feishu-cli search messages "上线" --enrich --format table

# 富化 + 控制卡片消息格式（仅 --enrich 生效）
feishu-cli search messages "告警" --enrich --card-content-type raw

# 富化 + 自动翻页（最多 5 页，防失控）
feishu-cli search messages "项目" --enrich --page-all --page-limit 5 --format csv

# 搜索私聊消息（search-chats 无法搜到 p2p 会话，用此方式替代）
feishu-cli search messages "你好" --chat-type p2p_chat

# 搜索群聊中的文件消息
feishu-cli search messages "周报" --chat-type group_chat --message-type file

# 搜索机器人消息
feishu-cli search messages "告警" --from-type bot

# 限定时间范围
feishu-cli search messages "项目" --start-time 1704067200 --end-time 1704153600

# 限定特定群
feishu-cli search messages "会议" --chat-ids oc_xxx,oc_yyy

Tip: the search chat API (search-chats）cannot find p2p private chat sessions. To find private chat content, use search messages --chat-type p2p_chat。

JSON output format

Default (no --enrich）：

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

The returned MessageIDs can use feishu-cli msg get <message_id> to get message details.

Add --enrich returns the enriched array:

[
  {
    "message_id": "om_xxx",
    "msg_type": "text",
    "chat_id": "oc_xxx",
    "chat_name": "项目群",
    "sender_id": "ou_xxx",
    "sender_name": "张三",
    "create_time": "1704067200000",
    "time": "2024-01-01 08:00:00",
    "text": "今天上线"
  }
]

---

Search apps

Search Feishu apps.scope: search:app(Feishu official registry scope name; you can search and enable it in Feishu Open Platform → Apps → Permission Management; this scope recommend=false, is not included automatically by auth login --recommend by default, and must be auth login --scope "search:app" explicitly requested. If it has been renamed on the Feishu side, the feishu-cli auth check --scope "search:app" error message takes precedence.)

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

Options

Parameter	Type	Description
--page-size	int	Number per page (default 20)
--page-token	string	Pagination token
-o json	string	JSON format output

Examples

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

---

FAQ

Issue	Cause	Solution
"Missing User Access Token"	Never logged in	Run the two-step login flow
"User Access Token expired"	Both access + refresh token expired	Log in again
99991679 permission error mentions search apps	Login scope does not include search:app, or this permission has not been enabled in Feishu Open Platform	feishu-cli auth login --scope "search:app"; if the error persists, go to the Permission Management page in Feishu Open Platform, search for search:app and enable it (contact the tenant admin for approval if necessary)
99991679 permission error mentions search:docs:read	Login did not include search:docs:read scope	Log in again, add search:docs:read
Search results are empty	Keywords do not match or there are no documents you have permission to access	Try broader keywords, or check document permissions
offset + count exceeds 200	Feishu API limitation	You can page through at most the first 200 results

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

---

Division of labor with other skills

Scenario	Skill to use
Search documents/apps by keyword	feishu-cli-search(this skill)
Search messages by keyword (including advanced filters)	feishu-cli-search(this skill)
Browse group chat history messages, search group chat lists	feishu-cli-chat
Reaction/Pin/delete/get message details	feishu-cli-chat
Group chat information management, member management	feishu-cli-chat

Difference between searching messages and browsing chat history: search (search messages) uses keywords to search across conversations and returns a list of message IDs; browse (msg history) retrieves a continuous stream of messages from a specified conversation. If the user's intent is "find messages containing a certain keyword", use search; for "see what a group has been chatting about recently", use browse.