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

feishu-cli-approval

General & other

View repository

Updated 10-16 04:59

About this skill

Feishu approval skill (query + write)

Complete the full approval lifecycle via feishu-cli: query approval definitions / approval instances / pending tasks, initiate / cancel / cc approval instances, approve / reject / transfer approval tasks.

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

Core concepts

Feishu approvals consist of four levels of objects, and commands are grouped by object:

Object Description Unique ID CLI subcommand
definition Approval definition (approval flow template, configured in the administrative/finance backend) approval_code approval get
instance Approval instance (a specific submission, bound to one definition + one form) instance_code approval instance {get,create,cancel,cc}
task Approval task (the to-do distributed from an instance to each approval node) task_id approval task {query,approve,reject,transfer}
cc CC (sends the instance to other users for their awareness, not an approval node) — approval instance cc

Lifecycle：get definition → submit form to trigger instance create → node user task approve/reject → the initiator can midway instance cancel or instance cc cc others.

Identity description (Token strategy)

approval get and approval instance create use Tenant Token (app identity), relying on the local app_id/app_secret to exchange for tenant_access_token。approval instance get、approval task query、approval instance cancel/cc、approval task approve/reject/transfer use User Token, must first auth login。

Required scope

Command scope Token type
approval get approval:approval:readonly Tenant is sufficient
approval instance get approval:instance:read User Token required
approval task query approval:task:read User Token required
approval instance create approval:approval Tenant
approval instance {cancel,cc} approval:instance:write User Token required
approval task {approve,reject} approval:task:write User Token required
approval task transfer approval:task:write User Token required 
# 用户态查询 / 处理审批需要用户授权；instance create 仍需应用态 approval:approval。
feishu-cli auth check --scope "approval:task:read approval:instance:read approval:instance:write approval:task:write"
feishu-cli auth login --scope "approval:task:read approval:instance:read approval:instance:write approval:task:write offline_access"

Command quick reference

Read

# 查审批定义（拿表单结构 / 节点列表，发起前必看）
feishu-cli approval get <approval_code>
feishu-cli approval get <approval_code> --output raw-json   # 原始 API

# 查我的审批任务
feishu-cli approval task query --topic todo                 # 待我审批
feishu-cli approval task query --topic done                 # 我已审批
feishu-cli approval task query --topic started              # 我发起的
feishu-cli approval task query --topic cc-unread            # 抄送给我（未读）
feishu-cli approval task query --topic cc-read              # 抄送给我（已读）

# 查单个审批实例详情
feishu-cli approval instance get --instance-code <ic>
feishu-cli approval instances get --instance-code <ic> --output raw-json

Write (added in v1.23+)

# 发起审批实例（form 必须是 JSON 数组）
feishu-cli approval instance create \
  --approval-code <code> \
  --user-id ou_xxx \
  --form-file form.json
#   或：--form '[{"id":"widget_1","type":"input","value":"内容"}]'

# 撤回（取消）已发起的审批实例（只有发起人能撤）
feishu-cli approval instance cancel \
  --instance-code <ic>

# 抄送实例给其他用户（逗号分隔，自动去重保留首次顺序）
feishu-cli approval instance cc \
  --instance-code <ic> \
  --cc-user-ids ou_a,ou_b \
  --comment "请知悉"

# 通过 / 拒绝审批任务
feishu-cli approval task approve \
  --instance-code <ic> --task-id <task> \
  --comment "同意"

feishu-cli approval task reject \
  --instance-code <ic> --task-id <task> \
  --comment "金额超预算"

# 转交审批任务（User Token）
feishu-cli approval task transfer \
  --instance-code <ic> \
  --task-id <task> \
  --transfer-user-id ou_target \
  --comment "请代审"

Key flag

--approval-code（instance create required)

Approval definition code, can be obtained from the approval get output or the Feishu backend approval management page URL. The CLI will first use isValidToken to validate the format.instance cancel/cc and task approve/reject/transfer use the official uat_* user-side API, only need --instance-code(the task series additionally requires --task-id), and do not accept --approval-code。

--user-id + --user-id-type

instance create indicates the initiator user ID, defaults to --user-id-type open_id（ou_xxx), the create endpoint only supports open_id / user_id, does not support union_id。

The official uat_* 's cancel, cc, approve, and reject will be executed under the current User Token identity, and no longer pass --user-id。task transfer 's --transfer-user-id indicates the transfer recipient,--user-id-type is used to indicate the type of this ID.

--form and --form-file

instance create support --form / --form-file choose one of the two;task approve supports --form directly pass a JSON string;task reject does not support form (the official uat_reject schema does not have this field).

form must be a JSON array, otherwise the CLI will first report on the client side "Form data must be a JSON array, parsing failed". Each element corresponds to a widget in the approval definition:

[
  {"id": "widget_1", "type": "input",    "value": "差旅报销 1500"},
  {"id": "widget_2", "type": "number",   "value": 1500},
  {"id": "widget_3", "type": "textarea", "value": "上海出差 3 天"}
]

The widget's id / type is read from the form field of approval get --output raw-json ,do not hand-code. Common types:input / textarea / number / radio / checkbox / date / attachmentV2 / fieldList(detail control, value is an array of arrays).

Each control value See the structure and JSON examples quick reference at references/form-control-values.md(14 types of control value structures + unsupported list + value sources), for reference when initiating an approval and filling out the form.

--cc-user-ids（instance cc required)

comma-separated list, e.g. ou_a,ou_b,ou_a. The CLI automatically trims + deduplicates via parseCommaSeparatedIDs , keeping the order of first occurrence, so passing the same ID repeatedly will cc only once. Empty strings are filtered out.

--comment(optional, shared by approve/reject/transfer/cc)

Approval comment / cc note.task reject It is recommended to fill in the rejection reason;task approve can usually be omitted;task transfer you can state the reason for the transfer.

--open-chat-id(only instance create）

The group ID to which the approval result is pushed; after initiation, a card is automatically sent in that group to update the approval status. Optional.

--user-access-token

Overrides the top of the token resolution chain. In most cases no need to specify; automatically reads the logged-in state from ~/.feishu-cli/token.json .

Complete examples

Example 1: From scratch to approving an expense reimbursement

# 1. 登录并预检用户态查询 / 处理 scope；发起实例还需在开放平台为应用开通 approval:approval
feishu-cli auth login --scope "approval:task:read approval:task:write approval:instance:read approval:instance:write offline_access"

# 2. 查审批定义拿 widget 结构
feishu-cli approval get 7AB12C... --output raw-json | jq '.form'

# 3. 准备 form.json
cat > /tmp/form.json <<'EOF'
[
  {"id": "widget_1", "type": "input",  "value": "差旅报销"},
  {"id": "widget_2", "type": "number", "value": 1500}
]
EOF

# 4. 发起实例（拿到 instance_code）
feishu-cli approval instance create \
  --approval-code 7AB12C... \
  --user-id ou_self \
  --form-file /tmp/form.json
# → 输出：审批实例已创建  instance_code: 8XY99Z...

# 5. 节点审批人通过任务（先在节点审批人电脑/账号上 auth login）
feishu-cli approval task query --topic todo   # 拿到 task_id
feishu-cli approval task approve \
  --instance-code 8XY99Z... \
  --task-id 99TASK... \
  --comment "同意"

# 可选：查看实例详情确认 timeline / task_list
feishu-cli approval instance get --instance-code 8XY99Z... --output json

Example 2: Initiate then cancel + cc

# 发起人撤回
feishu-cli approval instance cancel \
  --instance-code <ic>

# 抄送给 2 个同事（重复 ID 会去重）
feishu-cli approval instance cc \
  --instance-code <ic> \
  --cc-user-ids ou_a,ou_b,ou_a \
  --comment "供参考"

# 转交待办给其他审批人
feishu-cli approval task transfer \
  --instance-code <ic> --task-id <task> \
  --transfer-user-id ou_target \
  --comment "请代审"

Pitfalls

Problem Cause Solution
表单数据必须是 JSON 数组，解析失败 --form passed a {...} object Wrap in an array [{...}], Feishu form top level is always an array
--cc-user-ids Duplicate ID results in multiple cc No, the CLI already deduplicates (parseCommaSeparatedIDs） If multiple reminders are needed, execute multiple times instance cc
task approve returns forbidden The currently logged-in user is not the node approver / insufficient scope / the instance has ended First task query --topic todo to confirm the task is still there, and confirm the current auth login user is the approver
instance cancel failed The currently logged-in user is not the initiator / the instance has already been approved Only the initiator can cancel; instances that have been approved/rejected cannot be canceled
widget id not found Manual ID, does not match the backend definition First approval get --output raw-json to view the form field
auth login did not pass offline_access token expires after 1h and cannot be refreshed automatically Log in again and explicitly add --scope "... offline_access", Device Flow has already injected it automatically but confirm it
User Token missing The current command uses the official uat_* user-mode API First feishu-cli auth login, or explicitly pass --user-access-token

Output format

Write commands output a single-line success summary by default:

审批实例已创建
  instance_code: 8XY99Z...

Read commands approval get / approval instance get / task query support:

  • Not passing --output: human-readable text summary
  • --output json: CLI-normalized JSON
  • --output raw-json: raw Feishu API response (essential for getting widget structures / debugging)

approval instance create and approval task transfer both support --output json(the two are aligned, making it easy for scripts to consume the returned fields); other write commands output a text status and return non-0 on failure.

Not within the scope of this skill

Requirement Where to go
Visual approval flow design (drag nodes, configure approvers, set visibility scope) Feishu Admin "Approval Management" Web UI, not covered by the CLI
Send back / add approver / urge (tasks/rollback / add_sign / remind） The current official executable schema is not open yet, follow up via a PR as needed
Approval callback subscription / Webhook handling Not part of CLI responsibilities; goes through open platform event subscription
Notify approval result to group (message card) instance create --open-chat-id <chat> Built-in; or feishu-cli-msg Send custom card
Comment on approval document / add permissions feishu-cli-perm / comment commands; approval itself is not attached to the cloud document system

Related skill

  • /feishu-cli-auth — OAuth login, scope pre-check, token status
  • /feishu-cli-toolkit — Comprehensive query entry point (also has approval get / task query quick-reference sections)
  • /feishu-cli-msg — Secondary notification of approval result to group / individual