feishu-cli-auth

Name: feishu-cli-auth
Author: riba2534

INSTALLATION

npx skills add https://github.com/riba2534/feishu-cli --skill feishu-cli-auth

Run in your project or agent environment. Adjust flags if your CLI version differs.

SKILL.md

$27

常用命令

feishu-cli auth status

feishu-cli auth status -o json --verify

feishu-cli auth check --scope "REQ_SCOPES"

feishu-cli auth login --domain <domain> --recommend

feishu-cli auth logout

feishu-cli config create-app --save

auth status -o json 未登录时会包含：

{"logged_in": false, "identity": "bot", "note": "未登录，当前将使用 App Token"}

AI Agent 判断是否满足某个任务，优先用 auth check，不要只看 auth status。

Token 解析策略

场景

策略

默认命令

App Token，不自动加载用户 token

可选 User Token 命令

有 --user-access-token 或 FEISHU_USER_ACCESS_TOKEN 时用用户身份，否则 App Token

必须 User Token 命令

参数 → 环境变量 → ~/.feishu-cli/token.json（可自动刷新）→ config

登录时 CLI 会自动注入 offline_access 和 auth:user.id:read。如果 refresh_token_present=false，通常是应用未开通 offline_access，需要开通后重新登录。

必须 User Token 的典型命令

命令

典型 scope

search docs

search:docs:read

search messages

search:message

msg get/list/history/mget/thread-messages

im:message:readonly + 用户消息读取 scope

msg pin/unpin/pins

im:message.pins

msg reaction add/remove/list

im:message.reactions

msg search-chats、chat *

im:chat:*、im:chat.members:*

approval task query

approval:task

vc search/notes/recording、minutes *

vc:*、minutes:* 相关 scope

mail *

mail:user_mailbox:* 相关 scope

drive search

search:docs:read

msg delete 不是必须 User Token：默认 App Token 用于 Bot 自撤回；显式 User Token 可用于管理员撤回场景。

可选 User Token 的典型命令

wiki get/export/nodes

calendar list/get/event-search/freebusy

task create/complete/list、tasklist create/list/delete

user info/search

drive pull/push/status

这些命令默认 App Token；只有显式传 User Token 时才切换用户身份。

业务域登录

feishu-cli auth login --domain search --recommend

feishu-cli auth login --domain chat --recommend

feishu-cli auth login --domain vc --recommend

feishu-cli auth login --domain mail --recommend

多域可以显式传 scope；最终以 auth check --scope 结果为准。

排错

现象

处理

not_logged_in

执行 auth login --scope "..." --json

token_expired 且 refresh 可用

业务命令会自动刷新；也可重新登录

needs_relogin

refresh token 已过期，重新登录

missing_refresh_token

开通 offline_access 后 auth logout && auth login

99991672

access token 无效或过期，重新登录

99991679

应用未开通 scope，先在开放平台开通权限

Agent 约定

执行业务前先 auth check --scope，缺什么报什么。

登录用 --json 事件流，把 verification_uri_complete 给用户。

不把 user_access_token 写入文档、代码或日志。

auth logout 会清理 token 和用户 profile 缓存。