Feishu Search

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. Check Token Status

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. Log in to Get Token (if needed)

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

bash

# 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 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

# Step B: Exchange callback URL for Token
feishu-cli auth callback "<Callback URL provided by user>" --state "<state output from Step A>"

3. Perform Search

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

~/.feishu-cli/token.json

; no manual passing is required.

Search Cloud Docs

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

bash

feishu-cli search docs "keywords" [options]

Options

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)

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

# Basic search
feishu-cli search docs "product requirements"

# Search only new version docs and Wiki
feishu-cli search docs "technical solution" --docs-types docx,wiki

# Search spreadsheets
feishu-cli search docs "data report" --docs-types sheet

# Get more results with pagination
feishu-cli search docs "quarterly report" --count 50

# Pagination query: Get first page (20 results)
feishu-cli search docs "quarterly report" --count 20 --offset 0
# Pagination query: Get second page
feishu-cli search docs "quarterly report" --count 20 --offset 20

# Output in JSON format (suitable for program parsing)
feishu-cli search docs "product requirements" -o json

JSON Output Format

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

Search Feishu message records. Scope:
search:message

bash

feishu-cli search messages "keywords" [options]

Options

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

# Search messages
feishu-cli search messages "launch"

# Search private chat messages (search-chats cannot find p2p sessions, use this instead)
feishu-cli search messages "hello" --chat-type p2p_chat

# Search file messages in group chats
feishu-cli search messages "weekly report" --chat-type group_chat --message-type file

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

# Limit to time range
feishu-cli search messages "project" --start-time 1704067200 --end-time 1704153600

# Limit to specific groups
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 Output Format

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

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

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 "approval"
feishu-cli search apps "OKR" --page-size 50

Frequently Asked Questions

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.

feishu-cli-search

NPX Install

Tags

SKILL.md Content (Chinese)

Feishu Search

Execution Flow

1. Check Token Status

2. Log in to Get Token (if needed)

3. Perform Search

Search Cloud Docs

Options

Document Types (lowercase)

Examples

JSON Output Format

Search Messages

Options

Examples

JSON Output Format

Search Apps

Options

Examples

Frequently Asked Questions