Back to Details

feishu-cli-bitable

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

飞书多维表格（Bitable）操作

飞书多维表格（Bitable）操作

feishu-cli：如尚未安装，请前往 riba2534/feishu-cli 获取安装方式。
feishu-cli：如尚未安装，请前往 riba2534/feishu-cli 获取安装方式。

前置条件

前置条件

  • 认证：需要有效的 App Access Token（环境变量 
    FEISHU_APP_ID
    + 
    FEISHU_APP_SECRET
    ，或 
    ~/.feishu-cli/config.yaml
    ）
  • 权限：应用需开通 
    bitable:app
    （多维表格读写）
  • 验证：
    feishu-cli auth status
    确认认证状态正常
  • 认证：需要有效的 App Access Token（环境变量 
    FEISHU_APP_ID
    + 
    FEISHU_APP_SECRET
    ，或 
    ~/.feishu-cli/config.yaml
    ）
  • 权限：应用需开通 
    bitable:app
    （多维表格读写）
  • 验证：
    feishu-cli auth status
    确认认证状态正常

核心概念

核心概念

概念说明
app_token多维表格 URL 中 
/base/
后的字符串，标识一个多维表格
table_id数据表 ID，通过 
bitable tables
获取
record_id记录 ID，通过 
bitable records
获取
field_id字段 ID，通过 
bitable fields
获取
bitable ≠ sheet：
feishu-cli bitable
操作多维表格（Base），
feishu-cli sheet
操作电子表格（Sheets），两者是完全不同的产品和 API。
概念说明
app_token多维表格 URL 中 
/base/
后的字符串，标识一个多维表格
table_id数据表 ID，通过 
bitable tables
获取
record_id记录 ID，通过 
bitable records
获取
field_id字段 ID，通过 
bitable fields
获取
bitable ≠ sheet：
feishu-cli bitable
操作多维表格（Base），
feishu-cli sheet
操作电子表格（Sheets），两者是完全不同的产品和 API。

命令速查

命令速查

bash
undefined
bash
undefined

=== 多维表格 ===

=== 多维表格 ===

feishu-cli bitable create --name "项目管理" feishu-cli bitable create --name "数据库" --folder FOLDER_TOKEN feishu-cli bitable get <app_token>
feishu-cli bitable create --name "项目管理" feishu-cli bitable create --name "数据库" --folder FOLDER_TOKEN feishu-cli bitable get <app_token>

=== 数据表 ===

=== 数据表 ===

feishu-cli bitable tables <app_token> feishu-cli bitable create-table <app_token> --name "任务表" feishu-cli bitable rename-table <app_token> <table_id> --name "新表名" feishu-cli bitable delete-table <app_token> <table_id>
feishu-cli bitable tables <app_token> feishu-cli bitable create-table <app_token> --name "任务表" feishu-cli bitable rename-table <app_token> <table_id> --name "新表名" feishu-cli bitable delete-table <app_token> <table_id>

=== 字段管理 ===

=== 字段管理 ===

feishu-cli bitable fields <app_token> <table_id> feishu-cli bitable fields <app_token> <table_id> -o json # JSON 输出（含完整 property） feishu-cli bitable create-field <app_token> <table_id> --field '{"field_name":"状态","type":3,"property":{"options":[{"name":"进行中"},{"name":"已完成"}]}}' feishu-cli bitable update-field <app_token> <table_id> <field_id> --field '{"field_name":"新名称","type":1}' feishu-cli bitable delete-field <app_token> <table_id> <field_id>
feishu-cli bitable fields <app_token> <table_id> feishu-cli bitable fields <app_token> <table_id> -o json # JSON 输出（含完整 property） feishu-cli bitable create-field <app_token> <table_id> --field '{"field_name":"状态","type":3,"property":{"options":[{"name":"进行中"},{"name":"已完成"}]}}' feishu-cli bitable update-field <app_token> <table_id> <field_id> --field '{"field_name":"新名称","type":1}' feishu-cli bitable delete-field <app_token> <table_id> <field_id>

=== 记录操作 ===

=== 记录操作 ===

feishu-cli bitable records <app_token> <table_id> feishu-cli bitable records <app_token> <table_id> --page-size 100 feishu-cli bitable records <app_token> <table_id> --filter '{"conjunction":"and","conditions":[{"field_name":"状态","operator":"is","value":["进行中"]}]}' feishu-cli bitable records <app_token> <table_id> --sort '[{"field_name":"创建时间","desc":true}]' feishu-cli bitable records <app_token> <table_id> --field-names "名称,状态,金额" feishu-cli bitable get-record <app_token> <table_id> <record_id> feishu-cli bitable add-record <app_token> <table_id> --fields '{"名称":"测试","金额":100,"状态":"进行中"}' feishu-cli bitable add-records <app_token> <table_id> --data '[{"名称":"A","金额":100},{"名称":"B","金额":200}]' feishu-cli bitable add-records <app_token> <table_id> --data-file records.json feishu-cli bitable update-record <app_token> <table_id> <record_id> --fields '{"状态":"已完成"}' feishu-cli bitable delete-records <app_token> <table_id> --record-ids "recXXX,recYYY"
feishu-cli bitable records <app_token> <table_id> feishu-cli bitable records <app_token> <table_id> --page-size 100 feishu-cli bitable records <app_token> <table_id> --filter '{"conjunction":"and","conditions":[{"field_name":"状态","operator":"is","value":["进行中"]}]}' feishu-cli bitable records <app_token> <table_id> --sort '[{"field_name":"创建时间","desc":true}]' feishu-cli bitable records <app_token> <table_id> --field-names "名称,状态,金额" feishu-cli bitable get-record <app_token> <table_id> <record_id> feishu-cli bitable add-record <app_token> <table_id> --fields '{"名称":"测试","金额":100,"状态":"进行中"}' feishu-cli bitable add-records <app_token> <table_id> --data '[{"名称":"A","金额":100},{"名称":"B","金额":200}]' feishu-cli bitable add-records <app_token> <table_id> --data-file records.json feishu-cli bitable update-record <app_token> <table_id> <record_id> --fields '{"状态":"已完成"}' feishu-cli bitable delete-records <app_token> <table_id> --record-ids "recXXX,recYYY"

=== 视图管理 ===

=== 视图管理 ===

feishu-cli bitable views <app_token> <table_id> feishu-cli bitable create-view <app_token> <table_id> --name "看板" --type kanban feishu-cli bitable delete-view <app_token> <table_id> <view_id>

**别名**：`feishu-cli base` 等同于 `feishu-cli bitable`。
feishu-cli bitable views <app_token> <table_id> feishu-cli bitable create-view <app_token> <table_id> --name "看板" --type kanban feishu-cli bitable delete-view <app_token> <table_id> <view_id>

**别名**：`feishu-cli base` 等同于 `feishu-cli bitable`。

字段类型速查

字段类型速查

type中文名写入格式示例
1多行文本字符串
"文本内容"
2数字数值
100
（不要传字符串 
"100"
）
3单选字符串
"选项A"
（自动创建选项）
4多选字符串数组
["A","B"]
5日期13 位毫秒时间戳
1770508800000
7复选框布尔值
true
（建议用单选替代）
11人员对象数组
[{"id":"ou_xxx"}]
15超链接对象
{"text":"名称","link":"https://..."}
18单向关联字符串数组
["recuxxx"]
不支持 API 写入：公式、查找引用、创建时间、修改人、自动编号。
type中文名写入格式示例
1多行文本字符串
"文本内容"
2数字数值
100
（不要传字符串 
"100"
）
3单选字符串
"选项A"
（自动创建选项）
4多选字符串数组
["A","B"]
5日期13 位毫秒时间戳
1770508800000
7复选框布尔值
true
（建议用单选替代）
11人员对象数组
[{"id":"ou_xxx"}]
15超链接对象
{"text":"名称","link":"https://..."}
18单向关联字符串数组
["recuxxx"]
不支持 API 写入：公式、查找引用、创建时间、修改人、自动编号。

过滤运算符

过滤运算符

运算符说明适用类型
is等于文本/单选/数字
isNot不等于文本/单选/数字
contains包含文本/多选
doesNotContain不包含文本/多选
isEmpty为空所有类型
isNotEmpty不为空所有类型
isGreater大于数字/日期
isLess小于数字/日期
运算符说明适用类型
is等于文本/单选/数字
isNot不等于文本/单选/数字
contains包含文本/多选
doesNotContain不包含文本/多选
isEmpty为空所有类型
isNotEmpty不为空所有类型
isGreater大于数字/日期
isLess小于数字/日期

踩坑必读

踩坑必读

1. PUT fields 更新描述会清空单选选项

1. PUT fields 更新描述会清空单选选项

使用 
update-field
更新单选（type=3）字段时，必须带上完整的 property（含 options 列表），否则选项被清空，所有记录中该字段的值丢失。
正确做法：先用 
fields -o json
获取当前字段定义，合并修改后再更新：
bash
undefined
使用 
update-field
更新单选（type=3）字段时，必须带上完整的 property（含 options 列表），否则选项被清空，所有记录中该字段的值丢失。
正确做法：先用 
fields -o json
获取当前字段定义，合并修改后再更新：
bash
undefined

1. 获取当前字段定义

1. 获取当前字段定义

feishu-cli bitable fields <app_token> <table_id> -o json
feishu-cli bitable fields <app_token> <table_id> -o json

2. 更新时带上完整 property

2. 更新时带上完整 property

feishu-cli bitable update-field <app_token> <table_id> <field_id>
--field '{"field_name":"状态","type":3,"property":{"options":[{"name":"待处理"},{"name":"进行中"},{"name":"已完成"}]},"description":{"text":"任务状态"}}'
undefined
feishu-cli bitable update-field <app_token> <table_id> <field_id>
--field '{"field_name":"状态","type":3,"property":{"options":[{"name":"待处理"},{"name":"进行中"},{"name":"已完成"}]},"description":{"text":"任务状态"}}'
undefined

2. 创建 Base 默认表有空行

2. 创建 Base 默认表有空行

bitable create
创建多维表格时自动创建一张默认表，里面有空记录（约 10 行）。写入数据前建议先清理：
bash
undefined
bitable create
创建多维表格时自动创建一张默认表，里面有空记录（约 10 行）。写入数据前建议先清理：
bash
undefined

1. 列出所有记录

1. 列出所有记录

feishu-cli bitable records <app_token> <table_id> -o json
feishu-cli bitable records <app_token> <table_id> -o json

2. 找出空行的 record_id，批量删除

2. 找出空行的 record_id，批量删除

feishu-cli bitable delete-records <app_token> <table_id> --record-ids "rec1,rec2,rec3"
undefined
feishu-cli bitable delete-records <app_token> <table_id> --record-ids "rec1,rec2,rec3"
undefined

3. 不要用复选框（Checkbox），用单选替代

3. 不要用复选框（Checkbox），用单选替代

复选框在 GUI 上容易误触。改用单选（type=3）配置"是/否"选项：
bash
feishu-cli bitable create-field <app_token> <table_id> \
  --field '{"field_name":"必填","type":3,"property":{"options":[{"name":"是"},{"name":"否"}]}}'
复选框在 GUI 上容易误触。改用单选（type=3）配置"是/否"选项：
bash
feishu-cli bitable create-field <app_token> <table_id> \
  --field '{"field_name":"必填","type":3,"property":{"options":[{"name":"是"},{"name":"否"}]}}'

4. 主索引列重命名需带 type

4. 主索引列重命名需带 type

重命名 
is_primary=true
的字段时必须带 
type
字段，否则报 
99992402
：
bash
undefined
重命名 
is_primary=true
的字段时必须带 
type
字段，否则报 
99992402
：
bash
undefined

错误：缺少 type

错误：缺少 type

feishu-cli bitable update-field ... --field '{"field_name":"新名称"}'
feishu-cli bitable update-field ... --field '{"field_name":"新名称"}'

正确：带上 type

正确：带上 type

feishu-cli bitable update-field ... --field '{"field_name":"新名称","type":1}'
undefined
feishu-cli bitable update-field ... --field '{"field_name":"新名称","type":1}'
undefined

5. API 创建的表格默认不可见

5. API 创建的表格默认不可见

通过 API 创建的多维表格默认只有机器人能看到。创建后必须立即添加权限：
邮箱来源：
~/.feishu-cli/config.yaml
中的 
owner_email
，或环境变量 
FEISHU_OWNER_EMAIL
。
bash
undefined
通过 API 创建的多维表格默认只有机器人能看到。创建后必须立即添加权限：
邮箱来源：
~/.feishu-cli/config.yaml
中的 
owner_email
，或环境变量 
FEISHU_OWNER_EMAIL
。
bash
undefined

添加 full_access 权限

添加 full_access 权限

feishu-cli perm add <app_token> --doc-type bitable --member-type email --member-id <owner_email> --perm full_access --notification

如果配置了 `transfer_ownership: true`，还需转移所有权：
```bash
feishu-cli perm transfer-owner <app_token> --doc-type bitable --member-type email --member-id <owner_email>
feishu-cli perm add <app_token> --doc-type bitable --member-type email --member-id <owner_email> --perm full_access --notification

如果配置了 `transfer_ownership: true`，还需转移所有权：
```bash
feishu-cli perm transfer-owner <app_token> --doc-type bitable --member-type email --member-id <owner_email>

6. 关联字段的局限

6. 关联字段的局限

关联字段是"一列关联一张表"的设计，无法让不同行关联到不同子表。如果主表的不同记录需要对应到不同子表，直接靠命名约定（如工具名称 → 同名子表）更实用。
关联字段是"一列关联一张表"的设计，无法让不同行关联到不同子表。如果主表的不同记录需要对应到不同子表，直接靠命名约定（如工具名称 → 同名子表）更实用。

7. 数据格式注意

7. 数据格式注意

  • 数值不要传字符串：
    100
    而非 
    "100"
  • 日期必须是 13 位毫秒时间戳：
    1770508800000
  • 批量操作最多 500 条：超出需要分批处理
  • 数值不要传字符串：
    100
    而非 
    "100"
  • 日期必须是 13 位毫秒时间戳：
    1770508800000
  • 批量操作最多 500 条：超出需要分批处理

典型工作流

典型工作流

创建项目管理表

创建项目管理表

bash
undefined
bash
undefined

1. 创建多维表格

1. 创建多维表格

feishu-cli bitable create --name "项目管理" -o json
feishu-cli bitable create --name "项目管理" -o json

→ app_token

→ app_token

2. 查看默认表

2. 查看默认表

feishu-cli bitable tables <app_token>
feishu-cli bitable tables <app_token>

→ table_id

→ table_id

3. 添加字段

3. 添加字段

feishu-cli bitable create-field <app_token> <table_id> --field '{"field_name":"负责人","type":1}' feishu-cli bitable create-field <app_token> <table_id> --field '{"field_name":"状态","type":3,"property":{"options":[{"name":"待处理"},{"name":"进行中"},{"name":"已完成"}]}}' feishu-cli bitable create-field <app_token> <table_id> --field '{"field_name":"优先级","type":3,"property":{"options":[{"name":"P0"},{"name":"P1"},{"name":"P2"}]}}' feishu-cli bitable create-field <app_token> <table_id> --field '{"field_name":"截止日期","type":5}'
feishu-cli bitable create-field <app_token> <table_id> --field '{"field_name":"负责人","type":1}' feishu-cli bitable create-field <app_token> <table_id> --field '{"field_name":"状态","type":3,"property":{"options":[{"name":"待处理"},{"name":"进行中"},{"name":"已完成"}]}}' feishu-cli bitable create-field <app_token> <table_id> --field '{"field_name":"优先级","type":3,"property":{"options":[{"name":"P0"},{"name":"P1"},{"name":"P2"}]}}' feishu-cli bitable create-field <app_token> <table_id> --field '{"field_name":"截止日期","type":5}'

4. 清理默认空行

4. 清理默认空行

feishu-cli bitable records <app_token> <table_id> -o json feishu-cli bitable delete-records <app_token> <table_id> --record-ids "..."
feishu-cli bitable records <app_token> <table_id> -o json feishu-cli bitable delete-records <app_token> <table_id> --record-ids "..."

5. 批量写入数据

5. 批量写入数据

feishu-cli bitable add-records <app_token> <table_id> --data '[ {"标题":"完成需求文档","负责人":"张三","状态":"进行中","优先级":"P0"}, {"标题":"代码审查","负责人":"李四","状态":"待处理","优先级":"P1"} ]'
feishu-cli bitable add-records <app_token> <table_id> --data '[ {"标题":"完成需求文档","负责人":"张三","状态":"进行中","优先级":"P0"}, {"标题":"代码审查","负责人":"李四","状态":"待处理","优先级":"P1"} ]'

6. 添加权限

6. 添加权限

feishu-cli perm add <app_token> --doc-type bitable --member-type email --member-id user@example.com --perm full_access --notification
feishu-cli perm add <app_token> --doc-type bitable --member-type email --member-id user@example.com --perm full_access --notification

7. 创建看板视图

7. 创建看板视图

feishu-cli bitable create-view <app_token> <table_id> --name "状态看板" --type kanban
undefined
feishu-cli bitable create-view <app_token> <table_id> --name "状态看板" --type kanban
undefined

API 限制

API 限制

限制说明
批量操作上限单次最多 500 条记录
搜索分页page_size 最大 500
字段数量单表最多 200 个字段
默认空行新建表格自动创建约 10 行空记录
权限可见性API 创建的表格默认仅机器人可见
限制说明
批量操作上限单次最多 500 条记录
搜索分页page_size 最大 500
字段数量单表最多 200 个字段
默认空行新建表格自动创建约 10 行空记录
权限可见性API 创建的表格默认仅机器人可见

权限要求

权限要求

功能所需权限
多维表格读写
bitable:app
权限管理
docs:permission.member:create
所有权转移
docs:permission.member:create
功能所需权限
多维表格读写
bitable:app
权限管理
docs:permission.member:create
所有权转移
docs:permission.member:create