Use the official Feishu lark-cli to connect to a Feishu app explicitly authorized by the user, and separately perform read-only inventory, search, and document analysis for "Knowledge Base/Wiki" and "Cloud Drive/Drive". By default, use the app identity bot; only when the user explicitly requests access to a personal cloud drive, personal knowledge base, or private resources should user OAuth be used. By default, do not modify Feishu remote content; writing, moving, deleting, permission changes, sending messages, and exporting personal data must all be separately confirmed.
Scenario routing: Knowledge Base and Cloud Drive cannot be mixed
| Scenario | Default identity | Primary objects | When to use user OAuth | Detailed rules |
|---|---|---|---|---|
| Knowledge Base / Wiki | bot | Knowledge spaces, Wiki nodes, Wiki documents | The user explicitly requests a personal knowledge base or a private knowledge base not visible to the bot | wiki-workflow.md |
| Cloud Drive / Drive | bot | Shared folders, app-visible documents, file metadata | The user explicitly requests "my cloud drive / my folder / personal documents" | drive-workflow.md |
Do not treat Wiki space/node APIs as cloud drive directories, and do not interpret the bot's empty search results as the user's personal cloud drive being empty.
Two permission types: do they need to be requested at the same time
Feishu manages permissions for the same API capability separately by calling identity:
- App identity permissions：
tenant_access_token, at runtime it isbot. Request them on the "App identity permissions" tab; you also need to configure app data permissions, availability scope, or add the app to the target knowledge base/folder. - User identity permissions：
user_access_token, at runtime it isuser. Request them on the "User identity permissions" tab; then the user performslark-cli auth loginto complete OAuth, and the access scope follows the logged-in user.
If the goal is "Bot reads the enterprise knowledge base + user OAuth reads the personal cloud drive", you need to request the corresponding minimal read-only scopes separately on the two tabs. When using only one of the identities, do not repeatedly request the other permission. For the specific list, refer to permissions.yml in identity_modes .
Customer-readable explanation
What this skill can do
| Customer wants | Skill will do | Customer can see |
|---|---|---|
| Investigate Feishu cloud drive and knowledge base usage | Check app identity, visible spaces, node tree, document types, file and permission metadata | Structured inventory, accessed scope, invisible scope, and evidence commands |
| Read, summarize, or compare Feishu documents | First identify the URL type, then follow lark-doc rules to read the body and outline |
Document summary, citation locations, formatting, and permission restrictions |
| Search Feishu knowledge base, documents, and cloud drive | Use Drive Search or Wiki node queries, do not guess tokens and parameters | Matched documents, titles, types, spaces, and next-step reading scope |
| Install or repair the Feishu CLI | Install the official CLI, configure app credentials, and check the token, identity, scope, and connectivity | Command output summary; never print the App Secret or access token |
How customers use it
You can say directly:
- "Use the Feishu CLI to inventory the knowledge base hierarchy and cloud drive document types visible to me."
- "Read this Feishu Wiki page and determine which open-source self-hosted product it is better suited to migrate to."
- "Check which knowledge spaces and documents the Feishu app can currently see, and do not modify anything."
Before execution, parse source、target、scope、as and output. For this skill's research tasks, default to as=bot、read_only=true、dry_run=true(when write operations are involved); do not silently switch to user OAuth just because the bot cannot see the user's personal resources.
Dependencies and installation
| Dependency | Type | Install / Configure | What to do when missing |
|---|---|---|---|
| Node.js/npm or an environment that can run npx | Hard dependency | After installing Node.js, run npx @larksuite/cli@latest install |
Stop and explain that Node.js/npm needs to be installed |
Official lark-cli |
Hard dependency | npx @larksuite/cli@latest install; install the official companion skills as needed:npx skills add larksuite/cli -g -y |
Only public material research can be done; you cannot claim to have read the user's Feishu |
| Feishu app credentials | Hard dependency | Use profile add or this skill's script to write to the provider-owned CLI configuration |
Stop remote research; do not ask the user to send the Secret into the chat |
| API permissions already enabled for the Feishu app | Hard dependency | Enable the required scopes in the Feishu Open Platform; prefer read-only permissions | Record the missing scopes and the official console link |
After installation, run first:
lark-cli doctor
lark-cli profile list
lark-cli auth status --json --verify
lark-cli whoami
Permission enablement and app release
Before the first research task, or when the CLI returns an error, first readmachine-readable permission cataloganderror catalog, then follow thepermission enablement guideto explain the application process to the customer. First determine whether the target is a knowledge base or cloud drive, then determine whether to use bot or user OAuth; do not treat user OAuth scopes as bot permissions, and do not apply for write, delete, upload, or member management permissions just to read.
The Open Platform entry is concatenated from LARK_APP_ID in the private configuration:
https://open.feishu.cn/app/<APP_ID>/auth
The full loop must be completed: in "Development Configuration → Permission Management", enable and save according to the target API's permission requirements → check the tenant app data permissions and resource visibility scope → create a version for permissions requiring review and submit it for online release → wait for the enterprise administrator to approve → rerun setup_app_credentials.py --use、auth status --json --verify and representative read-only commands. Review-exempt permissions can be tested directly; "under review" is not considered to mean the permissions have officially taken effect.
Each time you report permissions back to the customer, divide them into three categories: "required", "optional", and "do not enable by default", and list the missing scopes, official console entry, and release steps; do not write the customer's real App ID into public skill files.
App credential login (bot mode)
App credentials are this skill's default login method and do not call lark-cli auth login as the default flow. App credentials only obtain a bot identity: it can only read resources that are visible to the app, granted app access, or allowed by tenant policies; it cannot automatically read personal knowledge bases, personal cloud drives, or private documents on behalf of a user.
It is recommended to place credentials in a skill-specific private configuration, not committed to the repository and not written into the vault:
~/.config/soia-skills/soia-open-skills/cwork/soia-cwork-feishu-cli/config.yml
SOIA_CWORK_FEISHU_CONFIG_FILE=<custom-config-path>
See the configuration example at assets/config.example.yml. The configuration may only contain placeholders or the user's own local values:
version: 1
env:
LARK_APP_ID: "<YOUR_APP_ID>"
LARK_APP_SECRET: "<YOUR_APP_SECRET>"
LARK_PROFILE: "feishu-reader"
LARK_BRAND: "feishu"
When using the configuration to initialize the app profile, the script passes the Secret via stdin, without putting the Secret into process arguments or logs:
python3 <skill-path>/scripts/setup_app_credentials.py
On first initialization or when the local profile does not exist, use --use to make it the current profile:
python3 <skill-path>/scripts/setup_app_credentials.py --use
When refreshing the App Secret, App ID, or brand of an existing profile, it must be explicitly initiated by the user, then use:
python3 <skill-path>/scripts/setup_app_credentials.py --replace --use
Because lark-cli does not allow the same App ID to exist in two profiles at the same time, refreshing will first delete the old profile and then write the new profile; therefore, only execute it when the private configuration has been confirmed correct and the user has explicitly requested a refresh. If the write fails, check the private configuration and rerun the initialization. After completion, verify:
lark-cli profile list
lark-cli auth status --json --verify
lark-cli whoami
lark-cli doctor
If invalid_client, error code 20140 , or "The auth method is not supported." appears, this is a profile/app credential authentication failure, not a missing scope; first fix the profile according to errors.yml , then check permissions.
If you need to switch a new profile to the default profile, you must explicitly use:
python3 <skill-path>/scripts/setup_app_credentials.py --use
The equivalent manual method is:
printf '%s' '<YOUR_APP_SECRET>' | lark-cli profile add \
--name feishu-reader \
--app-id '<YOUR_APP_ID>' \
--app-secret-stdin \
--brand feishu
Do not put LARK_APP_SECRET into shell history, command-line arguments, logs, commit records, or Feishu documents.auth login is user OAuth authorization, and can only be used when the user explicitly requests personal resources or explicitly specifies --as user .
User OAuth login (personal resources only)
When the user explicitly requests a personal cloud drive, personal knowledge base, or private resources, first read the corresponding wiki-workflow.md or drive-workflow.md, confirm the user identity scope, then use split-flow:
mkdir -p "${TMPDIR:-/tmp}/soia-cwork-feishu-cli"
lark-cli auth login --scope "<minimal-user-scopes>" --no-wait --json
lark-cli auth qrcode '<verification_url>' --output "${TMPDIR:-/tmp}/soia-cwork-feishu-cli/feishu-user-oauth.png"
After handing the authorization link and QR code to the user, end this round; after the user confirms completion, the agent executes lark-cli auth login --device-code <device_code>, then checks whether auth status --json --verify is user: ready. Do not treat user OAuth as a bot repair method, and do not silently switch identities when the user has not explicitly requested it.
The authentication chain must distinguish:
lark-cli auth login: the official CLI's user identity OAuth/device flow; only after completion willuser: ready。https://accounts.feishu.cn/oauth/v1/device/verify?...: the verification entry point for the CLI device flow. If it redirects toopen.feishu.cn/page/scope-authorizationand displays "application submitted, under review", it means the app's user identity scope or app version has not yet taken effect; this does not mean the user has completed login.https://open.feishu.cn/open-apis/authen/v1/user_info: the "get user info" API after login is complete, which requires an existinguser_access_token, and cannot be used as a login entry point.- If a self-built web app implements OAuth on its own, use the official authorization code endpoint
/open-apis/authen/v1/authorize, configureredirect_uri, then exchangeuser_access_token; do not manually assemble this URL for CLI tasks, as the CLI already wraps it with the device flow.
The same App ID can both generate the Bot's tenant_access_tokenand act as an OAuth client to generate the user's user_access_token; the page showing the same app name does not prove whether it is currently Bot or User. Use auth status --json --verify 's identities.bot / identities.user and the command's --as as the standard.
Read-only research workflow
- Check identity and scope：First readmachine-readable permission catalog，and when necessary readerror catalogandpermission enablement guide；Run
lark-cli auth status --json --verify、lark-cli whoami；record identity, profile, token status, and non-sensitive scope; do not output secrets. - Read the matching official embedded skill：Run
lark-cli skills read lark-shared；for knowledge base tasks readlark-wiki，for cloud drive tasks readlark-drive，and for body tasks additionally readlark-doc。Do not rely on--helpto guess parameters. - Inventory knowledge base/Wiki：Select identity by wiki-workflow.md ；bot runs
wiki +space-list/wiki +node-list，and user runs the corresponding--as usercommand only after explicit user authorization. Personal librarymy_librarycan only use the user identity. - Inventory cloud drive/Drive：Select identity by drive-workflow.md ；bot running Drive search can only cover app-visible resources, and personal cloud drive must explicitly complete OAuth first and then run
--as user。 - Read documents：First run using the corresponding identity
lark-cli drive +inspect --as <bot|user> --url '<URL>' --format jsonto parse the actual type and token; then followlark-docinstructions to use the corresponding identity'sdocs +fetch。 - Analyze migration requirements：Judge the target product only based on the structure, types, attachments, permissions, and collaboration traces that have already been read; write “seen,” “inferred,” and “unverified” separately.
- Verify：Re-paginate and check key counts; extract representative documents; check personal resources that are not visible to the bot and list them separately as gaps; if the API requires app data permissions, separately verify their data scope. Do not treat a single search result as a complete inventory.
For detailed commands and product boundaries, see references/cli-workflows.md。
Write operations and risk boundaries
- Read-only by default: search, list spaces, list nodes, read body content, view metadata, view comments, and view permissions.
- Create, edit, comment, upload, move, copy, export, download, public share, member management, delete, roll back, and send message all count as write or sensitive data actions; first present the target, scope, command, and impact, and wait for explicit user confirmation.
- When the CLI returns
confirmation_required，do not silently append--yes；hand high-risk actions to the user for confirmation. - When encountering
invalid_client/20140，do not classify it as a missing scope, and do not apply for permissions first; first fix the app credential profile. - When encountering a missing scope, preferably handle it according to the
console_urland missing scope in the error; do not silently switch the user OAuth, and start OAuth only when the user explicitly requests personal resources or explicitly specifies--as user。 - Do not read browser cookies, passwords, browser profiles, raw keychain contents, or token storage not provided by the user.
Logs and completion receipt
Each run must report at least:
started：CLI version, profile name, bot/user identity, non-sensitive scope, and investigation scope; do not print secrets.processed：The number of spaces, nodes, files, or documents, and whether pagination is complete.created/updated：By default write “remote unchanged”; if there are writes confirmed by the user, list the actual objects and results.skipped/failed：Insufficient permissions, bot invisibility, pagination limits, parsing failures, and reasons.verification: statuses run, schemas, pagination, sampled reads, and backup/export checks.
Recommended receipt:
完成：<一句话说明本次飞书调研或配置结果>。
日志摘要：
- started: <profile / identity / 非敏感范围>
- processed: <空间、节点、文档或文件数量>
- created/updated: 未改动远端 / <已确认的写入结果>
- skipped/failed: <数量和原因>
文件变化：
- <绝对路径或“未改动文件”>
验证：
- <运行过的 CLI 检查、分页核对、抽样读取>
问题与下一步：
- <缺 scope、bot 不可见资源、需要用户授权或无>
Resources
- Configuration example:assets/config.example.yml
- CLI workflow:references/cli-workflows.md
- Provider selection and credential boundaries:references/providers.md
- Source of truth for permissions:references/permissions.yml
- Knowledge base/Wiki workflow:references/wiki-workflow.md
- Cloud drive/Drive workflow:references/drive-workflow.md
- Source of truth for common errors:references/errors.yml
- Permission request process:references/permissions.md
- App credential initialization script:
scripts/setup_app_credentials.py
Verification
python3 <skill-path>/scripts/setup_app_credentials.py --help
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py <skill-path>
Repository-level verification is defined by soia-open-skills/AGENTS.md , at minimum run unit tests, skill directory generation checks, skill audits, and git diff --check。
forward testing
Before complex research or permission changes, first perform a forward test using anonymized fixtures or representative read-only objects explicitly authorized by the client: verify permission prompts, bot identity, count pagination, failure classification, and the final receipt; do not treat a command's successful exit as evidence of content completeness.