SuperAPI AI Directory

feishu-cli-bitable

General & other

View repository

Updated 10-15 16:43

About this skill

Lark Base (Bitable / Base)

Via base/v3 API operate on Lark Base.bitable Also supports the base alias.

API switch: This skill has switched from the old bitable/v1 to the new base/v3. The field names app_token and base_token are two names for the same value in Lark docs (old v1 calls it app_token, new v3 calls it base_token); the CLI only recognizes --base-token(--app-token has been removed). From the Base URL, just take the token from the /base/<token> or /bitable/<token> fragment.

Prerequisites

  • Authentication: All commands support --as bot|user|auto identity switching (see "Identity Selection" below), default auto(User first, Tenant fallback). When logged in, User Token is used; when not logged in, it automatically falls back to App Token; to reliably run with App Token (cron), explicitly add --as bot
  • App credentials: App ID + App Secret (base/v3 requires the X-App-Id header, injected automatically).--as bot / auto When falling back to Tenant, it relies only on App credentials, no auth login

Identity Selection --as(command group persistent flag, common to all subcommands)

Lark base/v3 and bitable/v1 API itself supports both User and Tenant(App) identities at the same time, so this skill provides three modes accordingly:

--as Identity When to use Whether auth login
autois needed (default) User first, Tenant fallback Interactive daily use No (automatically uses App Token when not logged in)
bot(= tenant/app) Force App Token cron / unattended / scripted automatic scraping, never expires No
user Force User Token Must operate as oneself (personal base, collaborator permissions) Yes (error if missing)
# cron 场景:App 凭证走环境变量,App Token 抓多维表格,不依赖登录、不会过期
export FEISHU_APP_ID=cli_xxx FEISHU_APP_SECRET=xxx
feishu-cli bitable table list  --base-token bscnxxxx --as bot
feishu-cli bitable record list --base-token bscnxxxx --table-id tblxxx --as bot
feishu-cli bitable record upsert --base-token bscnxxxx --table-id tblxxx \
  --config '{"fields":{"文本":"hello"}}' --as bot

--as bot reports 91403 you don't have permission: It's not a token issue, it's that the Bot is not yet a collaborator on this Base. Add the Bot as a collaborator (feishu-cli perm add <base_token> --doc-type bitable --member-type open_id --member-id <bot_open_id> --perm full_access) or set the document visibility to organization-visible. A base created by the Bot itself has permissions by default. Historical background: The old bitable command forcibly required User Token on the CLI side (direct error if not logged in), but the underlying API has always supported Tenant Token—it has now been opened up according to the official lark-cli 's --as mode.

Command Quick Reference

Basics (4 commands)

# 创建多维表格
feishu-cli bitable create --name "项目管理" --time-zone Asia/Shanghai
feishu-cli bitable create --name "销售" --folder-token fldxxx

# 获取多维表格信息
feishu-cli bitable get --base-token bscnxxxx

# 复制多维表格
feishu-cli bitable copy --base-token bscnxxxx --name "副本"
feishu-cli bitable copy --base-token bscnxxxx --name "空白副本" --without-content

# 更新多维表格本体:重命名 / 开关高级权限(仅显式设置的字段才提交)
feishu-cli bitable update --base-token bscnxxxx --name "新表名"
feishu-cli bitable update --base-token bscnxxxx --is-advanced true   # 开启高级权限

update goes through bitable/v1(PUT apps/{app_token}, base/v3 has no update-body endpoint; app_token is base_token), only supports Bases within cloud space folders.--is-advanced true/false is equivalent to advperm enable/disable 's advanced permissions toggle.

Data table (5 commands)

feishu-cli bitable table list   --base-token bscnxxxx
feishu-cli bitable table get    --base-token bscnxxxx --table-id tblxxx
feishu-cli bitable table create --base-token bscnxxxx --name "任务表"
feishu-cli bitable table create --base-token bscnxxxx --config-file table.json
feishu-cli bitable table update --base-token bscnxxxx --table-id tblxxx --name "新名字"
feishu-cli bitable table delete --base-token bscnxxxx --table-id tblxxx

Field (6 commands)

feishu-cli bitable field list           --base-token xxx --table-id tblxxx
feishu-cli bitable field get            --base-token xxx --table-id tblxxx --field-id fldxxx
feishu-cli bitable field create         --base-token xxx --table-id tblxxx --config-file field.json
feishu-cli bitable field update         --base-token xxx --table-id tblxxx --field-id fldxxx --config '...'
feishu-cli bitable field delete         --base-token xxx --table-id tblxxx --field-id fldxxx
feishu-cli bitable field search-options --base-token xxx --table-id tblxxx --field-id fldxxx --query "关键词"

Record (14 commands)

feishu-cli bitable record list        --base-token xxx --table-id tblxxx --view-id viewxxx --limit 100
feishu-cli bitable record get         --base-token xxx --table-id tblxxx --record-id recxxx
feishu-cli bitable record batch-get   --base-token xxx --table-id tblxxx --record-ids recxxx,recyyy
# batch-get 可选 flag:返回分享链接 / 自动计算字段 / 指定用户字段 ID 类型
feishu-cli bitable record batch-get   --base-token xxx --table-id tblxxx --record-ids recxxx,recyyy \
  --with-shared-url --automatic-fields --user-id-type open_id   # user-id-type: open_id|union_id|user_id
# record search:用 --keyword(推荐),不要混用 upsert 的 {"fields":{...}}
feishu-cli bitable record search      --base-token xxx --table-id tblxxx --keyword 测试 --search-field 名称
# 结构化过滤用 --filter-json(遵循 base/v3 records/search 规范)或 --config 传完整请求体

# upsert:不传 --record-id 则 POST 创建;传 --record-id 则 PATCH 更新(官方无专用 upsert 端点)
feishu-cli bitable record upsert      --base-token xxx --table-id tblxxx --config '{"fields":{"名称":"测试"}}'
feishu-cli bitable record upsert      --base-token xxx --table-id tblxxx --record-id recxxx --config '{"fields":{"状态":"完成"}}'

feishu-cli bitable record batch-create --base-token xxx --table-id tblxxx --config-file records.json
feishu-cli bitable record batch-update --base-token xxx --table-id tblxxx --config-file records.json
feishu-cli bitable record delete      --base-token xxx --table-id tblxxx --record-id recxxx

# batch-delete:POST /records/batch_delete,单次最多 500 条;--record-ids CSV 或 --from-file 任选其一
feishu-cli bitable record batch-delete --base-token xxx --table-id tblxxx --record-ids rec_1,rec_2,rec_3
feishu-cli bitable record batch-delete --base-token xxx --table-id tblxxx --from-file ids.txt   # 每行一个 record_id

# share-link:批量生成记录共享链接(v1.29+ 新增),单次最多 100 条
feishu-cli bitable record share-link  --base-token xxx --table-id tblxxx --record-ids rec_1,rec_2,rec_3

# history-list:GET + query params(不是 POST body),--record-id 必填
feishu-cli bitable record history-list --base-token xxx --table-id tblxxx --record-id recxxx
feishu-cli bitable record history-list --base-token xxx --table-id tblxxx --record-id recxxx --page-size 50 --max-version 20

# 附件:upload/download 为 2 步编排(medias/upload_all + append/get_attachments),单次 ≤50 个
feishu-cli bitable record upload-attachment   --base-token xxx --table-id tblxxx \
  --record-id recxxx --field-id fldxxx --file ./report.pdf --file ./shot.png   # --file 可重复
feishu-cli bitable record download-attachment --base-token xxx --table-id tblxxx \
  --record-id recxxx --output ./downloads/                                     # 省略 --file-token 下全部
feishu-cli bitable record download-attachment --base-token xxx --table-id tblxxx \
  --record-id recxxx --file-token boxcnxxxx --output ./a.pdf --overwrite       # 指定单个附件,已存在则覆盖
feishu-cli bitable record remove-attachment   --base-token xxx --table-id tblxxx \
  --record-id recxxx --field-id fldxxx --file-token boxcnxxxx                   # --file-token 可重复

Attachment filename:download-attachment uses attachmentOriginal filenameSave (no longer named by file_token); if the target already exists it will error directly, add --overwrite to overwrite. All three attachment commands support --dry-run(preview the request body before writing);upload/remove-attachment supports --format/--jq,download-attachment does not support (only prints JSON).

View view (5 commands + 12 config commands)

# 基础 CRUD
feishu-cli bitable view list   --base-token xxx --table-id tblxxx
feishu-cli bitable view get    --base-token xxx --table-id tblxxx --view-id viewxxx
feishu-cli bitable view create --base-token xxx --table-id tblxxx --name "看板视图" --view-type kanban
feishu-cli bitable view delete --base-token xxx --table-id tblxxx --view-id viewxxx
feishu-cli bitable view rename --base-token xxx --table-id tblxxx --view-id viewxxx --name "新名字"

# 视图配置 get/set(6 种 × 2 = 12 命令)— set 方法是 PUT(全量替换)
feishu-cli bitable view view-filter-get        --base-token xxx --table-id tblxxx --view-id viewxxx
feishu-cli bitable view view-filter-set        --base-token xxx --table-id tblxxx --view-id viewxxx \
  --config '{"filter_info":{"conjunction":"and","conditions":[{"field_id":"fld1","operator":"is","value":["进行中"]}]}}'

feishu-cli bitable view view-sort-get          --base-token xxx --table-id tblxxx --view-id viewxxx
# sort/group 的 --config 可传数组,自动包装为 {"sort_config":[...]} / {"group_config":[...]}
feishu-cli bitable view view-sort-set          --base-token xxx --table-id tblxxx --view-id viewxxx \
  --config '[{"field_id":"fld1","desc":false}]'

feishu-cli bitable view view-group-get         --base-token xxx --table-id tblxxx --view-id viewxxx
feishu-cli bitable view view-group-set         --base-token xxx --table-id tblxxx --view-id viewxxx \
  --config '[{"field_id":"fld1"}]'

feishu-cli bitable view view-visible-fields-get --base-token xxx --table-id tblxxx --view-id viewxxx
# visible-fields 必须传完整对象(不会自动包装)
feishu-cli bitable view view-visible-fields-set --base-token xxx --table-id tblxxx --view-id viewxxx \
  --config '{"view_field":[{"field_id":"fld1","visible":true},{"field_id":"fld2","visible":true}]}'

feishu-cli bitable view view-timebar-get       --base-token xxx --table-id tblxxx --view-id viewxxx
feishu-cli bitable view view-timebar-set       --base-token xxx --table-id tblxxx --view-id viewxxx \
  --config '{"timebar":{"start_field_id":"fld_start","end_field_id":"fld_end","title_field_id":"fld_title"}}'

feishu-cli bitable view view-card-get          --base-token xxx --table-id tblxxx --view-id viewxxx
feishu-cli bitable view view-card-set          --base-token xxx --table-id tblxxx --view-id viewxxx \
  --config '{"card":{"cover_field_id":"fld1","display_fields":["fld2","fld3"]}}'

View config auto-wrapping rules(reduce user boilerplate):

  • view-sort-set can directly pass [{...}] array, automatically wrapped into {"sort_config":[...]}
  • view-group-set can directly pass [{...}] array, automatically wrapped into {"group_config":[...]}
  • Other config (filter/visible-fields/timebar/card) must pass the complete object

View config JSON Schema quick reference:

// view-filter(过滤条件)
{
  "filter_info": {
    "conjunction": "and",
    "conditions": [
      {"field_id": "fldxxx", "operator": "is", "value": ["进行中"]}
    ]
  }
}

// view-sort(排序)
{
  "sort_config": [
    {"field_id": "fldxxx", "desc": false}
  ]
}

// view-group(分组)
{
  "group_config": [{"field_id": "fldxxx"}]
}

// view-visible-fields(可见字段)
{
  "view_field": [{"field_id": "fld1", "visible": true}, {"field_id": "fld2", "visible": false}]
}

// view-timebar(甘特图时间轴)
{"timebar": {"start_field_id": "fld1", "end_field_id": "fld2", "title_field_id": "fld3"}}

// view-card(卡片/画册视图)
{"card": {"cover_field_id": "fld1", "display_fields": ["fld2", "fld3"]}}

Role role (5 commands + collaborator member 5 commands)

feishu-cli bitable role list   --base-token xxx
feishu-cli bitable role get    --base-token xxx --role-id roxxx
feishu-cli bitable role create --base-token xxx --config-file role.json
feishu-cli bitable role update --base-token xxx --role-id roxxx --config '...'
feishu-cli bitable role delete --base-token xxx --role-id roxxx

Role collaborator role member (5 commands)

Add or remove users/groups/departments from a role (via bitable/v1 collaborator endpoint apps/{app_token}/roles/{role_id}/members)。

feishu-cli bitable role member list         --base-token xxx --role-id roxxx           # 支持 --page-size(≤100)/--page-token
feishu-cli bitable role member create       --base-token xxx --role-id roxxx --member-id ou_xxx
feishu-cli bitable role member delete       --base-token xxx --role-id roxxx --member-id ou_xxx
# 批量增删:--member-ids 逗号分隔,单次 ≤100
feishu-cli bitable role member batch-create --base-token xxx --role-id roxxx --member-ids ou_a,ou_b,ou_c
feishu-cli bitable role member batch-delete --base-token xxx --role-id roxxx --member-ids ou_a,ou_b

--member-id-type defaults to open_id, optional open_id|union_id|user_id|chat_id|department_id|open_department_id(corresponds to the ID type of --member-id/--member-ids ). member write commands (create/delete/batch-create/batch-delete) all support --dry-run/--format/--jq。 scope differs: role member goes through the collaborator endpoint, the required scope is bitable:app / bitable:app:readonly / base:collaborator:read,not base:role—requesting only base:role will hit 99991679.

Advanced permissions advperm (2 commands)

feishu-cli bitable advperm enable  --base-token xxx
feishu-cli bitable advperm disable --base-token xxx

Data aggregation data-query (1 command)

⚠️ base/v3's data-query endpoint is attached at the base level(not table level), sodoes not need --table-id。

feishu-cli bitable data-query --base-token xxx --config-file query.json
feishu-cli bitable data-query --base-token xxx --config '{"dimensions":[{"field_id":"fld_cat"}],"measures":[{"field_id":"fld_amt","type":"sum"}]}'

Underlying call:POST /open-apis/base/v3/bases/{base_token}/data/query

Query body example (LiteQuery DSL:dimensions / measures / filters, consistent with the above --config ):

{
  "dimensions": [{"field_id": "fld_category"}],
  "measures": [{"field_id": "fld_amount", "type": "sum"}]
}

Workflow workflow (6 commands)

feishu-cli bitable workflow list   --base-token xxx --page-size 50 --status enabled
feishu-cli bitable workflow list   --base-token xxx --page-token TOKEN
feishu-cli bitable workflow get    --base-token xxx --workflow-id wkfxxxx          # 含 steps
feishu-cli bitable workflow create --base-token xxx --config '{"title":"My Workflow","steps":[...]}'
feishu-cli bitable workflow update --base-token xxx --workflow-id wkfxxxx --config-file wf.json  # PUT 整体替换
feishu-cli bitable workflow enable  --base-token xxx --workflow-id wkfxxxx
feishu-cli bitable workflow disable --base-token xxx --workflow-id wkfxxxx

update is a PUT full replacement, fields not provided are not retained;workflow_id is wkf prefix. Private endpoint: public OpenAPI only documents workflow list(read-only),create/get/update/enable/disable goes through the base/v3 private extension endpoint (if you hit limits you can use feishu-cli api raw call as a fallback). Write commands (create/update/enable/disable) all support --dry-run/--format/--jq。

Dashboard dashboard (7 commands + dashboard block block 5 commands)

# 仪表盘 CRUD(原有 list/copy);create/update 支持便捷字段 --name/--theme-style 或 --config/--config-file
feishu-cli bitable dashboard list    --base-token xxx
feishu-cli bitable dashboard copy    --base-token xxx --dashboard-id dsbxxxx --name "副本"
feishu-cli bitable dashboard create  --base-token xxx --name "运营看板"
feishu-cli bitable dashboard get     --base-token xxx --dashboard-id dsbxxxx
feishu-cli bitable dashboard update  --base-token xxx --dashboard-id dsbxxxx --name "新名字"
feishu-cli bitable dashboard delete  --base-token xxx --dashboard-id dsbxxxx
feishu-cli bitable dashboard arrange --base-token xxx --dashboard-id dsbxxxx     # 服务端智能排版,无 body

# 仪表盘块 block CRUD;create --type 取值见下
feishu-cli bitable dashboard block create --base-token xxx --dashboard-id dsbxxxx \
  --type column --name "按月统计" --data-config '{"table_name":"任务","group_by":[{"field_id":"fld_month"}]}'
feishu-cli bitable dashboard block list   --base-token xxx --dashboard-id dsbxxxx
feishu-cli bitable dashboard block get    --base-token xxx --dashboard-id dsbxxxx --block-id blkxxxx
feishu-cli bitable dashboard block update --base-token xxx --dashboard-id dsbxxxx --block-id blkxxxx --name "新块名"
feishu-cli bitable dashboard block delete --base-token xxx --dashboard-id dsbxxxx --block-id blkxxxx

block --type values:column|bar|line|pie|ring|area|combo|scatter|funnel|wordCloud|radar|statistics|text; chart block --data-config pass table_name/series|count_all/group_by/filter, text block pass text。--data-config 's internal structure is defined by the Feishu chart schema, with no local offline validation (--dry-run also does not validate internal fields), it is recommended to use block get to first get the structure of an existing chart block as a template before modifying. --theme-style write into theme.theme_style, valid values are defined by the Feishu dashboard theme schema (the CLI does not perform enum validation); when unsure, omit this field to use the default theme, or dashboard get a dashboard that already has a theme configured to see its actual values. dashboard / block all write commands (create/update/delete/copy/arrange) support --dry-run preview request body; all commands support --format json|pretty|table|ndjson|csv and --jq。

Form form (7 commands + form question field 4 commands)

# 表单 CRUD(原有 get/patch)
feishu-cli bitable form create --base-token xxx --table-id tblxxx --name "报名表" --description "活动报名"
feishu-cli bitable form list   --base-token xxx --table-id tblxxx                    # 列出表下所有表单,支持 --page-size(≤100)/--page-token
feishu-cli bitable form get    --base-token xxx --table-id tblxxx --form-id vewxxx
feishu-cli bitable form patch  --base-token xxx --table-id tblxxx --form-id vewxxx --name "新名字"
# patch 一键开启共享(走 bitable/v1,shared 系字段才生效)
feishu-cli bitable form patch  --base-token xxx --table-id tblxxx --form-id vewxxx \
  --shared true --shared-limit anyone_editable --submit-limit-once true
feishu-cli bitable form delete --base-token xxx --table-id tblxxx --form-id vewxxx   # form_id 即表单视图 view_id

# 按分享 token(shr 前缀)取详情 / 提交,无需 base_token
feishu-cli bitable form detail --share-token shrcnxxxx
feishu-cli bitable form submit --share-token shrcnxxxx --content '{"评分":5,"评价":"很好"}'  # 不处理附件

# 表单问题 field(别名 questions):list/patch + 批量 create/delete(单次 ≤10)
feishu-cli bitable form field list   --base-token xxx --table-id tblxxx --form-id vewxxx
feishu-cli bitable form field create --base-token xxx --table-id tblxxx --form-id vewxxx \
  --questions '[{"type":"text","title":"你的名字","required":true}]'
feishu-cli bitable form field patch  --base-token xxx --table-id tblxxx --form-id vewxxx --config-file q.json
feishu-cli bitable form field delete --base-token xxx --table-id tblxxx --form-id vewxxx --question-ids fld001,fld002

Form question fields:title(required)/type(text/number/select/datetime/user/attachment/location)/description/required/multiple/options etc.;submit if attachments are needed, first use record upload-attachment approach to get file_token then write into --content。 form patch goes through bitable/v1(different from the base/v3 of other form commands): because --shared/--shared-limit/--submit-limit-once are bitable/v1 fields, the whole thing is routed to bitable/v1 so that share-related fields take effect at once.--shared-limit Values:off | tenant_editable | anyone_editable; only convenience fields that are explicitly set are submitted; for complex scenarios you can use --config/--config-file to pass the full request body raw. form submit's --content is a raw field map(e.g. {"评分":5}),do notwrap {"fields":{...}}— the CLI no longer auto-unwraps; adding an extra layer will lose data. All form/field write commands (create/patch/delete, field create/patch/delete, detail/submit) support --dry-run preview; all form commands support --format/--jq;form create/patch、field create/delete all support --config/--config-file passing the full request body raw as an escape hatch for convenience fields.

Typical workflow

create table → add fields → write data → create view and configure filters

# 1. 创建多维表格
BASE_TOKEN=$(feishu-cli bitable create --name "任务跟踪" -o json | jq -r '.base.base_token')

# 2. 创建数据表
TABLE_ID=$(feishu-cli bitable table create --base-token $BASE_TOKEN --name "待办" | jq -r '.table.table_id')

# 3. 添加字段
feishu-cli bitable field create --base-token $BASE_TOKEN --table-id $TABLE_ID --config '{
  "field": {"name": "状态", "type": "select", "property": {"options": [{"name": "待办"}, {"name": "进行中"}, {"name": "完成"}]}}
}'

# 4. 批量写入记录
feishu-cli bitable record batch-create --base-token $BASE_TOKEN --table-id $TABLE_ID --config-file records.json

# 5. 创建自定义视图
VIEW_ID=$(feishu-cli bitable view create --base-token $BASE_TOKEN --table-id $TABLE_ID --name "进行中" --view-type grid | jq -r '.view.view_id')

# 6. 配置视图过滤
feishu-cli bitable view view-filter-set --base-token $BASE_TOKEN --table-id $TABLE_ID --view-id $VIEW_ID --config '{
  "filter_info": {
    "conjunction": "and",
    "conditions": [{"field_id": "fld_status", "operator": "is", "value": ["进行中"]}]
  }
}'

# 7. 配置排序(按创建时间降序)
feishu-cli bitable view view-sort-set --base-token $BASE_TOKEN --table-id $TABLE_ID --view-id $VIEW_ID --config '{
  "sort_config": [{"field_id": "fld_create_time", "desc": true}]
}'

Permission requirements

Command Required scope
Read operations (list/get/search/history) base:app:readonly、base:table:readonly、base:record:readonly、base:field:readonly、base:view:readonly
Write operations (create/update/delete/batch) base:app、base:table、base:record、base:field、base:view
Role management base:role:readonly / base:role
Role collaborators (role member) bitable:app:readonly / bitable:app / base:collaborator:read(goes through the bitable/v1 collaborator endpoint,not base:role)
Advanced permissions base:app_permission
Workflows Read base:workflow:readonly / Write base:workflow
Dashboards / forms Read base:dashboard:readonly / base:form:readonly, write base:dashboard / base:form

Notes

  • base/v3 requires the X-App-Id header: the command injects it automatically, no manual setting needed
  • base_token / app_token are the same value: Feishu's old and new docs use two different names; the CLI only recognizes --base-token(--app-token already deleted)
  • --config / --config-file two kinds of input: all write operations support inline JSON or a file path
  • --dry-run preview (only supported by write commands newly added in this round):--dry-run is only available on write commands newly added in this round——dashboard/block writes,form/form field writes,workflow create/update/enable/disable、role member writes,record upload/download/remove-attachment、bitable update。Old write commands do not support(record batch-create/batch-update/upsert/delete、table/field/view/role create·update·delete、advperm enable/disable、bitable create/copy etc. passing --dry-run will report unknown flag). The new commands' dry-run also respects --format/--jq(download-attachment's dry-run always prints to stdout, and does not write to --output)。
  • --format / --jq output control (supported by about 40% of commands, mostly newly added in this round): supports --format json|pretty|table|ndjson|csv(default json) + --jq(built-in gojq) are mainly the newly added commands in this round (record batch-get、bitable update、dashboard/form/role member/workflow each command, etc.), you can --jq '.items[].name' extract or --format table tabulate.A large number of old commands do not support:record list/get/search/批量写、table/field/view/role list·CRUD、view-*-get/set、bitable create/copy/data-query/advperm、record download-attachment etc.——these print JSON directly (some use the old-style -o json); when you need filtering, switch to feishu-cli api ... --jq or external jq.
  • Batch limit:record batch-create / batch-update is limited by the Feishu backend; it is recommended that a single batch be ≤500 items
  • View type:view create --view-type Optional values:grid / kanban / gallery / gantt / calendar
  • Attachment commands are orchestration commands: upload goes through medias/upload_all + append_attachments, download goes through get_attachments + medias/{ft}/download, ≤50 at a time
  • form_id = view_id: a form's form_id is the view_id of the form view;detail/submit Use share-token(shr prefix, extracted from the share link) no base_token required
  • still uses Feishu private extension APIs (there is no corresponding public OpenAPI; you can use feishu-cli api raw call as a fallback): view independent filter-sort endpoint (base-api.feishu.cn)