SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsfeishu-cli-schema

feishu-cli-schema

Coding & development

View repository

Updated 10-16 01:57

About this skill

Feishu OpenAPI browsing + invocation skill

The combined punch of two commands:

  • feishu-cli schema — locally query an OpenAPI method's path/verb/parameters/scope/doc link (purely local, no Token / no network required)
  • feishu-cli api — directly call any Feishu OpenAPI endpoint (v1.29+, automatic authentication + error code translation, covering 2500+ unwrapped endpoints)

Typical workflow:schema list 发现 → schema get 看参数 + scope → feishu-cli auth check/login add scope → feishu-cli api invoke.

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

Core concepts

Path format:<service>.<resource>.<method>

segment meaning example
service business domain im / docs / drive / bitable / calendar / vc / mail / wiki / approval / sheets / slides / task / attendance / minutes
resource resource (may contain ., matched by longest prefix) messages / events / records / chat.members
method action create / get / list / update / delete / patch

Automatically dispatched by path depth:

  • schema no parameters → list all services
  • schema <service> → list all resource.method under that service
  • schema <service>.<resource> → list all methods under the resource
  • schema <service>.<resource>.<method> → method details (including path / parameters / scope / docUrl)

Data source

compile-time embedded embed 's internal/registry/meta_data.json(about 690KB), sharing the same metadata with auth check and other modules. Currently covers 12 services：approval / attendance / calendar / drive / im / mail / minutes / sheets / slides / task / vc / wiki。

Command quick reference

1. List all services

feishu-cli schema
# 等价：
feishu-cli schema list

Output table:name | version | resources 数 | title。

2. List all methods of a service

feishu-cli schema im                       # 列出 im 域全部 resource.method
feishu-cli schema list --service im        # 等价（推荐用 list，语义更清楚）
feishu-cli schema list --service im --format json

pretty output grouped by resource, listing HTTP verb + method 名 + description；json output flat {service, resource, method, path, httpMethod, description} list, convenient for AI Agent secondary processing.

3. List methods under a resource

feishu-cli schema im.messages              # messages 资源下所有 method
feishu-cli schema im.chat.members          # 含点号的 resource（最长前缀匹配）

4. Look up specific method details

feishu-cli schema im.messages.delete
feishu-cli schema im.messages.delete --format json

pretty output includes:

  • HTTP verb + full URL path (/open-apis/im/v1/messages/{message_id}）
  • method description
  • Parameters (including path / query / required marker + type + description + example)
  • Request Body (only shown for POST/PUT/PATCH/DELETE, including nested fields)
  • Response Body
  • Identity：tenant (bot) / user(specifies which Token is supported)
  • Scopes: permission points required for invocation
  • Docs: official Feishu Open Platform documentation link

Key flag

flag effect applicable
--format pretty(default) human-readable, table + indented field tree terminal reading
--format json raw JSON (HTML not escaped) AI Agent parsing, script assembly
--service <name> only schema list subcommand, filter service equivalent to schema <service>

Common use cases

1. Find whether Feishu has a certain API

feishu-cli schema list --service drive | grep -i comment

2. Look up parameters before assembling a call

feishu-cli schema im.chats.create
# 然后用 feishu-cli api 或 feishu-cli chat create 调用

3. AI Agent gets JSON to infer invocation

feishu-cli schema sheets.spreadsheets.create --format json

4. Confirm the scope requirements of a method

feishu-cli schema vc.meeting.get
# 看 Identity / Scopes 行即可

🔥 Golden combo: schema lookup → api call (v1.29+)

feishu-cli api <method> <path> is the generic OpenAPI passthrough command of v1.29+, forming a complete loop with schema.

Complete workflow

# Step 1: schema 查 path + scope + token 类型
feishu-cli schema im.chats.create
# 输出: POST /open-apis/im/v1/chats
#       Identity: tenant (bot)
#       Scopes:   im:chat

# Step 2: scope 不够时补
feishu-cli auth check --scope "im:chat"
feishu-cli auth login --scope "im:chat"          # 缺则补

# Step 3: 直接调（无需写代码 / 无需 curl）
feishu-cli api POST /open-apis/im/v1/chats \
  --data '{"name":"测试群","description":"by feishu-cli api"}' \
  --as bot

feishu-cli api key flag

Flag purpose
--params '<json>' Query parameters
--data '<json>' Body（POST/PUT/PATCH）
--data-file <path> Body read from file (- means stdin)
--as bot|user|auto Force identity; auto = user first, fallback to bot
--dry-run Only print the request, do not actually call
--format json|pretty|table|ndjson|csv Response rendering format (once specified, uses built-in rendering, overriding the default pretty)
--jq '<expr>' Built-in gojq filters the response (no external jq needed)
--raw Output as-is (default pretty JSON)
--include-headers Print response headers to stderr
--output <file> / -o Write to file instead of stdout (-o binary download and --format/--jq are mutually exclusive, see feishu-cli-api skill）
--timeout <seconds> Custom timeout (default 30s)

Built-in error code translation (v1.29+)

feishu-cli api When a Feishu business error is received, it automatically prints a Chinese solution, covering:

  • 99991661/99991663/99991668/99991672/99991679/99991677 → Token invalid or insufficient permissions
  • 99991400 → Rate limited
  • 230001/230002/230020 → Insufficient scope, prompts auth check --scope
  • 232033 → Insufficient external group permissions (prompts to switch to an externally shared App)
  • 232011 → Bot/user not in the group
  • 232006 → chat_id invalid
  • 232025 → App has not enabled the Bot capability

Smart URL handling

  • Automatically strips the https://open.feishu.cn / larksuite.com / larkoffice.com prefix
  • Automatically adds the /open-apis/ prefix
  • Automatically splits the embedded ?query=string in the URL into query parameters
  • Automatically ignores #fragment
# 这几种等价：
feishu-cli api GET /open-apis/authen/v1/user_info --as user
feishu-cli api GET /authen/v1/user_info --as user
feishu-cli api GET https://open.feishu.cn/open-apis/authen/v1/user_info --as user
feishu-cli api GET 'https://xxx.feishu.cn/open-apis/authen/v1/user_info?foo=bar#hash' --as user

and feishu-cli-shared relationship with the skill

If you want other tools (curl/Python) to reuse the token without going through this command, use feishu-cli auth token --as user/bot to export the token string (see feishu-cli-auth skill）。

Pitfalls

  1. Path too deep will report an error：schema im.messages.delete.foo → 路径过深: ...（多余片段: foo）. Writing one extra level will not be silently swallowed.
  2. Graded hints for nonexistent paths: unknown service / resource / method will all list all available candidate names at that level, making it easy to correct.
  3. resource containing dots uses longest prefix matching：im.chat.members.create will match resource = chat.members、method = create, no need to worry about splitting it wrong.
  4. Read-only, does not call the API: this command never makes HTTP requests, consumes no quota, and has no token expiration concerns. To actually call, see "When to switch to other skills" below.
  5. Coverage = 12 services: currently covers approval / attendance / calendar / drive / im / mail / minutes / sheets / slides / task / vc / wiki;does not include business domains such as docx / bitable(base) / contact / authen / board / okr / tenant / application; if schema list does not list it, it means the local metadata does not include it, please check the latest online version in Feishu OpenAPI Explorer (or the corresponding dedicated feishu-cli <模块> command in this project usually already wraps it).
  6. JSON output does not escape HTML：< / > / & is kept as-is, making it easy to pipe directly into jq / yq.

When to switch to other skills

Requirement What to use
Call the API and this project has a corresponding business command feishu-cli <模块> corresponding command (msg / doc / bitable / drive…) —— better experience
Call the API but there is no corresponding business command / want to go directly through OpenAPI introduced by this skill feishu-cli api <method> <path>（v1.29+）
get a token for curl/Python feishu-cli auth token --as user/bot(see feishu-cli-auth skill）
Check the latest online schema, not included locally Feishu OpenAPI Explorer
Investigate "buried APIs" (not included in the Feishu documentation site) See feishu-cli-toolkit/references/embedded-api-discovery.md, 6 buried APIs known
Request scope / log in to get a User Token /feishu-cli-auth（auth check --scope pre-check,auth login --domain --recommend apply by business domain)
Specific business such as messaging/docs/cards /feishu-cli-msg / /feishu-cli-read / /feishu-cli-card and other specialized skills