base

Prerequisites: Read
../lark-shared/SKILL.md
first. Mandatory before execution: Before running any
base
command, you must read the corresponding command reference document first, then invoke the command. Naming convention: Only use commands in the form of
lark-cli base +...
.

Agent Quick Execution Sequence

First determine the task type
- Temporary statistics / aggregate analysis →
```
+data-query
```
- Need to display results in the table long-term → formula field
- User explicitly requests lookup, or it is indeed more suitable for
```
from/select/where/aggregate
```
  → lookup field
- Detail reading / export →
```
+record-list / +record-get
```
Retrieve structure first, then write commands
- At least retrieve the current table structure first:
```
+field-list
```
  or
```
+table-get
```
- For cross-table scenarios, you must also retrieve the structure of the target table
Formula / lookup have hard thresholds
- Read the corresponding guide first
- After reading the guide, create the corresponding field
Determine field writability before writing records
- Only write to storage fields
- System fields / formula / lookup are read-only by default

Agent Prohibited Behaviors

Do not use
```
+record-list
```
as an aggregate analysis engine
Do not create formula / lookup fields without reading the guide first
Do not guess table names, field names, or field references in formula expressions based on natural language
Do not use system fields, formula fields, or lookup fields as the target for
```
+record-upsert
```

Do not switch to

lark-cli api GET /open-apis/bitable/v1/...

for Base scenarios

Do not look for
```
bitable.*
```
just because
```
obj_type=bitable
```
appears in wiki parsing results; continue to use
```
lark-cli base +...
```
in this CLI

Basic Mental Model of Base

Base fields are divided into three categories
- Storage fields: Store user input data, typically suitable for
```
+record-upsert
```
  writing, such as text, number, date, single-select, multi-select, member, association. Exception for attachment fields: For agents, file upload must go through the
```
+record-upload-attachment
```
  link.
- System fields: Automatically maintained by the platform, read-only, typically including creation time, last update time, creator, modifier, auto-number.
- Calculated fields: Derived via expressions or cross-table rules, read-only, typically including formula fields and lookup fields.
Determine field category before writing records — Only storage fields can be written directly; formula / lookup / creation time / update time / creator / modifier / auto-number should be treated as read-only output fields and cannot be used as parameters for
```
+record-upsert
```
.
Base is not just for storing table data, it can also build-in calculations — When users put forward requirements like "statistics, comparison, ranking, text concatenation, date difference, cross-table summary, status judgment", do not default to exporting data and calculating manually; first determine whether it should be completed within Base via
```
+data-query
```
or formula fields.

Analysis Path Decision

One-time analysis / temporary query → Prioritize
```
+data-query
```
- Suitable for: Group statistics, SUM / AVG / COUNT / MAX / MIN, aggregation after conditional filtering.
- Feature: Needs "results calculated this time", not to沉淀 results as fields in the table.
Long-term reusable derived metrics / row-level calculation results → Prioritize formula fields
- Suitable for: Profit margin, whether delayed, remaining days, grading tags, derived results after cross-table summary.
- Feature: Needs to display results in Base long-term, which update automatically with records.
Explicitly requires Lookup, or indeed suitable for modeling with source/select/where/aggregate → Use lookup fields
- Default to prioritizing formula. Only use lookup when users explicitly request it, or when the configuration is naturally more suitable for lookup.
Raw record reading / detail export →
```
+record-list / +record-get
```
- Do not use
```
+record-list
```
  as an analysis engine; it is responsible for retrieving details, not aggregation calculations.

Formula / Lookup Special Rules

When involving formula / lookup, read the guide first, then write commands
- formula:
  formula-field-guide.md
- lookup:
  lookup-field-guide.md
Guide takes precedence over creation commands
- Do not create formula / lookup fields without reading the corresponding guide first
- After reading the guide, complete the corresponding JSON and create the field
- ```
type=formula
```
  must provide
```
expression
```
- ```
type=lookup
```
  must provide
```
from / select / where
```
  , and supplement
```
aggregate
```
  if necessary
Formula fields take precedence over lookup fields
- As long as the user's requirement is "calculation / conditional judgment / text processing / date difference / cross-table aggregation / value retrieval after cross-table filtering", default to trying formula first.
- Only use lookup when users explicitly mention it, or when the configuration is naturally more suitable for the lookup four-tuple.
Table names / field names must match exactly
- Table names / field names used in formulas, lookup, data-query must come from the actual returns of
```
+table-list
```
  /
```
+table-get
```
  /
```
+field-list
```
  ; guessing and rewriting based on semantics is prohibited.
Retrieve structure first, then write expressions
- For formulas or lookup, always retrieve the relevant table structure first, then generate expressions / configurations; do not directly assemble field names based on user口述.

Workflow Special Rules

Before executing any workflow command, you must read two documents: the corresponding command document + lark-base-workflow-schema.md
- ```
+workflow-create
```
  → Read lark-base-workflow-create.md + schema first
- ```
+workflow-update
```
  → Read lark-base-workflow-update.md + schema first
- ```
+workflow-list
```
  → Read lark-base-workflow-list.md + schema first
- ```
+workflow-get
```
  → Read lark-base-workflow-get.md + schema first
- ```
+workflow-enable
```
  → Read lark-base-workflow-enable.md + schema first
- ```
+workflow-disable
```
  → Read lark-base-workflow-disable.md + schema first
- The schema defines all StepType enums, step structures, data formats of Trigger/Action/Branch/Loop, value reference syntax, etc.
- Prohibit guessing
```
type
```
  values based on natural language (e.g., guessing "add record" as
```
CreateTrigger
```
  ); must copy the exact type name from the StepType enum in the schema
Confirm dependency information before creation
- First retrieve actual table names and field names via
```
+table-list
```
  /
```
+field-list
```
- Prohibit guessing table names/field names based on natural language and filling them into workflow configurations

Core Rules

Only use atomic commands — Use commands like

+table-list / +table-get / +field-create / +record-upsert / +view-set-filter / +record-history-list / +base-get

which perform one action per command, instead of the old aggregate-style

+table / +field / +record / +view / +history / +workspace

Read field structure before writing records — First call
```
+field-list
```
to retrieve field structure, then read lark-base-shortcut-record-value.md to confirm the write value format for each field type
Check field property specifications before writing fields — First read lark-base-shortcut-field-properties.md to confirm the JSON structure for
```
+field-create/+field-update
```
Execute filter queries according to view capabilities — First read lark-base-view-set-filter.md and lark-base-record-list.md, and complete filter reading via the combination of
```
+view-set-filter
```
+
```
+record-list
```
Analyze records (involving analysis intentions like "highest/lowest/total/average/ranking/comparison/quantity") — First read lark-base-data-query.md, and perform server-side calculation of data filtering and aggregation via
```
+data-query
```
Aggregation analysis and data retrieval are mutually exclusive — When group statistics / SUM / MAX / AVG / COUNT are needed, must use
```
+data-query
```
(server-side calculation); prohibit pulling all records with
```
+record-list
```
and then calculating manually; conversely,
```
+data-query
```
does not return raw records, so data retrieval scenarios still use
```
+record-list / +record-get
```

All
+xxx-list
commands are prohibited from concurrent calls —

+table-list / +field-list / +record-list / +view-list / +record-history-list / +role-list

can only be executed serially

Batch limit: 500 items per time — It is recommended to write to the same table serially, with a 0.5–1 second delay between batches
Unified parameter name — Always use
```
--base-token
```
, do not use the old
```
--app-token
```
For requirements involving "formula / lookup reference / derived metric / cross-table calculation", prioritize field scheme judgment — First determine whether to create formula / lookup fields, or just perform a one-time
```
+data-query
```
Formula, lookup, and system fields are read-only by default — Except for maintaining field definitions via
```
+field-create / +field-update
```
, do not use these fields as record writing targets
Execute renaming and deletion according to explicit intentions —
```
+view-rename
```
can be executed directly when both the target view and new name are clear;
```
+record-delete / +field-delete / +table-delete
```
can also be executed directly when the user has clearly requested deletion and the target is clear, no need for additional confirmation, and
```
--yes
```
must be actively added when executing the delete command; only continue to ask questions when the target is unclear

Form / Questionnaire Tips

Get questionnaire list: Use
```
+form-list
```
(get
```
form-id
```
first)
Get single questionnaire: Use
```
+form-get
```
Get form / questionnaire questions: Use
```
+form-questions-list
```
Delete questionnaire / form questions: Use
```
+form-questions-delete
```

Create / update questions: Use

+form-questions-create / +form-questions-update

Intent → Command Index

Intent	Recommended Command	Remarks
List / Get data tables	`lark-cli base +table-list` / `+table-get`	Atomic command
Create / Update / Delete data tables	`lark-cli base +table-create` / `+table-update` / `+table-delete`	One action per command
List / Get fields	`lark-cli base +field-list` / `+field-get`	Atomic command
Create / Update fields	`lark-cli base +field-create` / `+field-update`	Use `--json`
Create / Update formula fields	`lark-cli base +field-create` / `+field-update`	`type=formula` ; Read formula guide first, then create / update
Create / Update lookup fields	`lark-cli base +field-create` / `+field-update`	`type=lookup` ; Read lookup guide first, then create / update; Default to judging whether formula is more suitable
List / Get records	`lark-cli base +record-list` / `+record-get`	Atomic command; For `aggregate calculation` or `group statistics` , it is recommended to use `+data-query`
Create / Update records	`lark-cli base +record-upsert`	`--table-id [--record-id] --json`
Aggregate analysis / Comparison sorting / Get min/max / Filter statistics	`lark-cli base +data-query`	Do not use `+record-list` to pull all records and then calculate manually; use `+data-query` instead
Configure / Query views	`lark-cli base +view-*`	`list/get/create/delete/get-/set-/rename`
View record history	`lark-cli base +record-history-list`	Query record history by table and record
Filter query by view	`lark-cli base +view-set-filter` + `lark-cli base +record-list`	Combined call
Create / Get / Copy Base	`lark-cli base +base-create` / `+base-get` / `+base-copy`	Atomic command
List / Get workflows	`lark-cli base +workflow-list` / `+workflow-get`	Atomic command
Create / Update workflows	`lark-cli base +workflow-create` / `+workflow-update`	Use `--json` ; Must read schema
Enable / Disable workflows	`lark-cli base +workflow-enable` / `+workflow-disable`	One action per command
Enable / Disable advanced permissions	`lark-cli base +advperm-enable` / `+advperm-disable`	Advanced permissions must be enabled to use custom roles; Disabling will invalidate existing roles
List / Get roles	`lark-cli base +role-list / +role-get`	View role summary or complete configuration
Create / Update / Delete roles	`lark-cli base +role-create / +role-update / +role-delete`	Manage custom role permissions
List / Get forms	`lark-cli base +form-list` / `+form-get`	Atomic command
Create / Update / Delete forms	`lark-cli base +form-create` / `+form-update` / `+form-delete`	One action per command
List / Create / Update / Delete form questions	`lark-cli base +form-questions-list` / `+form-questions-create` / `+form-questions-update` / `+form-questions-delete`	One action per command
List / Get dashboards	`lark-cli base +dashboard-list` / `+dashboard-get`	Atomic command
Create / Update / Delete dashboards	`lark-cli base +dashboard-create` / `+dashboard-update` / `+dashboard-delete`	One action per command
List / Get dashboard Blocks	`lark-cli base +dashboard-block-list` / `+dashboard-block-get`	Atomic command
Create / Update / Delete dashboard Blocks	`lark-cli base +dashboard-block-create` / `+dashboard-block-update` / `+dashboard-block-delete`	One action per command

Operation Notes

Unified Base token specification: Use
```
--base-token
```
uniformly

Discipline for
+xxx-list
calls: Concurrent calls to

+table-list / +field-list / +record-list / +view-list / +record-history-list / +role-list / +dashboard-list / +dashboard-block-list / +workflow-list

are prohibited; must execute serially during batch execution

+record-list
limit upper limit: The maximum value of
```
--limit
```
is
```
200
```
. When more data is needed, must use pagination (increment
```
offset
```
) to pull in batches; passing more than
```
200
```
at a time is prohibited
Determine field writability first: Only storage fields can be written; formula / lookup / system fields are read-only by default and should be skipped when writing records
Proactively consider formula capabilities: When users say "calculate" "generate tags" "judge abnormality" "cross-table summary" "alert by date difference", first determine whether formula fields should be created instead of only returning manual analysis solutions
Lookup is not the default first choice: Lookup is only used when users explicitly request it or it is indeed more suitable for fixed lookup models; formula is prioritized for regular calculations, cross-table aggregation and conditional judgments
Attachment fields: If users want to "upload attachments / add files to records", only use the
```
+record-upload-attachment
```
link (read field → read record → upload material → write back record)
Member fields / User fields: Pay attention to the difference between
```
user_id_type
```
and execution identity (user / bot) during debugging
History usage:
```
+record-history-list
```
queries record history by
```
table-id + record-id
```
, and does not support full-table history scanning
Workspace status: Integrated with
```
+base-create / +base-get / +base-copy
```
Result return specification for
+base-create / +base-copy
: After successful creation or copying, the identification information of the new Base must be actively returned in the reply. If the return result contains an accessible link (such as
```
base.url
```
), it should also be returned together
Friendliness rules for
+base-create / +base-copy
:
```
--folder-token
```
,
```
--time-zone
```
, and
```
--name
```
during copying are optional parameters. Do not interrupt the process for these optional parameters when users have no special requirements; execute creation/copy directly if possible
Permission handling for
+base-create / +base-copy
(bot creation): If the Base is created by an application identity (bot), after successful creation or copying, continue to use the bot identity to add
```
full_access
```
(administrator) permission to the currently available user (referring to the user identity that has logged in and is available in the auth module of the current CLI), and clearly state the authorization result (success / no available user / authorization failure and reason) in the reply. If authorization is not completed, provide subsequent guidance (retry authorization later or continue using bot); owner transfer must be confirmed separately, unauthorized execution is prohibited
Dashboard usage:
```
+dashboard-create
```
returns
```
dashboard_id
```
after creation;
```
data_config
```
of Block is passed in via JSON string, and supports reading files via
```
@file.json
```
Advperm usage: Advanced permissions must be enabled via
```
+advperm-enable
```
to manage roles (
```
+role-*
```
);
```
+advperm-disable
```
is a high-risk operation, and all existing custom roles will become invalid after disabling; the operating user must be a Base administrator; read lark-base-advperm-enable.md / lark-base-advperm-disable.md first
Role usage:
```
+role-create
```
only supports
```
custom_role
```
;
```
+role-update
```
uses Delta Merge (
```
role_name
```
and
```
role_type
```
must always be provided);
```
+role-delete
```
is irreversible and only supports custom roles; role configuration supports
```
base_rule_map
```
(Base-level copy/download),
```
table_rule_map
```
(table-level permissions including record/field granularity),
```
dashboard_rule_map
```
(dashboard permissions),
```
docx_rule_map
```
(document permissions); read role-config.md before writing roles
Form form-id: Obtained via
```
+form-list
```
; The
```
id
```
returned by
```
+form-create
```
is
```
form-id
```
, which can be used for
```
+form-questions-*
```
operations
Workflow usage: Before creating or updating a workflow, you must carefully read lark-base-workflow-schema.md to understand the structure of each trigger and node component; meanwhile,
```
+workflow-list
```
does not return the complete tree structure, so use
```
+workflow-get
```
if you need to read the complete structure.
Data-query usage: Before using
```
+data-query
```
, you must read lark-base-data-query.md to understand the DSL structure, supported field types, aggregation functions and restrictions;
```
field_name
```
in DSL must match the table field name exactly, retrieve real field names with
```
+field-list
```
before constructing
Formula / lookup usage: Before constructing expressions or where conditions, at least retrieve the current table structure first; for cross-table scenarios, retrieve the structure of the target table; guessing field names based on natural language is not allowed
View rename confirmation rule: When the user has clearly specified "which view to rename to what name",
```
+view-rename
```
can be executed directly without additional confirmation
Delete confirmation rule (records / fields / tables): If the user has clearly stated to delete and the target is clear,
```
+record-delete / +field-delete / +table-delete
```
can be executed directly without additional confirmation; add
```
--yes
```
directly when executing to pass the CLI's high-risk write check. Only use
```
+record-get / +field-get / +table-get
```
or list commands to confirm when the target is ambiguous

Special Handling of Wiki Links (Extremely Critical!)

Knowledge base links (

/wiki/TOKEN

) may correspond to different document types such as cloud documents, spreadsheets, multidimensional tables, etc. Do not directly assume that the token in the URL is the file_token; you must first query the actual type and real token.

Processing Flow

Query node information using
wiki.spaces.get_node

bash

lark-cli wiki spaces get_node --params '{"token":"&lt;wiki_token&gt;"}'

Extract key information from the return result
- ```
node.obj_type
```
  : Document type (docx/doc/sheet/bitable/slides/file/mindnote)
- ```
node.obj_token
```
  : Real document token (used for subsequent operations)
- ```
node.title
```
  : Document title
Select subsequent commands based on
obj_type
| obj_type | Description | Subsequent Commands | |----------|------|-----------| |
```
docx
```
| New version cloud document |
```
drive file.comments.*
```
、
```
docx.*
```
| |
```
doc
```
| Old version cloud document |
```
drive file.comments.*
```
| |
```
sheet
```
| Spreadsheet |
```
sheets.*
```
| |
```
bitable
```
| Multidimensional table |
```
lark-cli base +...
```
(priority); if shortcut does not cover, use
```
lark-cli base <resource> <method>
```
; Do not switch to
```
lark-cli api /open-apis/bitable/v1/...
```
| |
```
slides
```
| Slides |
```
drive.*
```
| |
```
file
```
| File |
```
drive.*
```
| |
```
mindnote
```
| Mind map |
```
drive.*
```
|
Use
obj_token
parsed from wiki as Base token
- When
```
obj_type=bitable
```
  ,
```
node.obj_token
```
  is the real token that should be used for subsequent
```
base
```
  commands.
- That is: If the original input is a
```
/wiki/...
```
  link, do not directly use
```
wiki_token
```
  as
```
--base-token
```
  .
If token error occurs, fallback to check wiki
- If the command returns
```
param baseToken is invalid
```
  ,
```
base_token invalid
```
  ,
```
not found
```
  , and the user initially provided a
```
/wiki/...
```
  link or
```
wiki_token
```
  , first suspect that "wiki token is used as base token".
- At this time, do not switch to
```
bitable/v1
```
  API; immediately re-execute
```
lark-cli wiki spaces get_node
```
  , confirm
```
obj_type=bitable
```
  , then re-execute
```
lark-cli base +...
```
  using
```
node.obj_token
```
  .

Query Example

bash

# Query wiki node
lark-cli wiki spaces get_node --params '{"token":"Pgrr***************UnRb"}'

Return result example：

json

{
  "node": {
    "obj_type": "docx",
    "obj_token": "UAJ***************E9nic",
    "title": "ai friendly test - 1 copy",
    "node_type": "origin",
    "space_id": "6946843325487906839"
  }
}

Base Link Parsing Rules

Link Type	Format	Handling Method
Direct Base link	`/base/{token}`	Extract directly as `--base-token`
Wiki knowledge base link	`/wiki/{token}`	Call `wiki.spaces.get_node` first, then take `node.obj_token`

URL Parameter Extraction

https://{domain}/base/{base-token}?table={table-id}&view={view-id}

```
/base/{token}
```
→
```
--base-token
```
```
?table={id}
```
→
```
--table-id
```
```
?view={id}
```
→
```
--view-id
```

Prohibited Items

Prohibit directly passing the complete URL as the
```
--base-token
```
parameter
Prohibit directly using wiki_token as
```
--base-token
```

Quick Check of Common Errors

Error Code	Meaning	Solution
1254064	Incorrect date format	Use millisecond timestamp instead of string / second-level timestamp
1254068	Incorrect hyperlink format	Use `{text, link}` object
1254066	Member field error	Use `[{id:"ou_xxx"}]` , and confirm `user_id_type`
1254045	Field name does not exist	Check field name (including spaces, case)
1254015	Field value type mismatch	Call `+field-list` first, then construct according to type
`param baseToken is invalid` / `base_token invalid`	Wiki token, workspace token or other tokens are used as `base_token`	If the input comes from a `/wiki/...` link or `wiki_token` , first use `lark-cli wiki spaces get_node` to retrieve the real `obj_token` ; when `obj_type=bitable` , use `node.obj_token` as `--base-token` to retry, do not switch to `bitable/v1` API
Formula / lookup creation failed	Guide not read or structure is invalid	Read `formula-field-guide.md` / `lookup-field-guide.md` first, then rebuild the request according to the guide
Failed to write to system fields / formula fields	Read-only fields are treated as writable	Switch to writing storage fields, and let formula / lookup / system fields automatically generate calculation results
1254104	Batch exceeds 500 items	Call in batches
1254291	Concurrent write conflict	Write serially + add delay between batches

Reference Documents

lark-base-shortcut-field-properties.md — JSON specification for
```
+field-create/+field-update
```
(recommended)
role-config.md — Detailed explanation of role permission configuration
lark-base-shortcut-record-value.md — Value format specification for
```
+record-upsert
```
(recommended)
formula-field-guide.md — Formula field syntax, function constraints, CurrentValue rules, cross-table calculation mode (highly recommended)
lookup-field-guide.md — Lookup field configuration rules, where/aggregate constraints, trade-off with formula
lark-base-view-set-filter.md — View filter configuration
lark-base-record-list.md — Record list reading and pagination
lark-base-advperm-enable.md —
```
+advperm-enable
```
to enable advanced permissions
lark-base-advperm-disable.md —
```
+advperm-disable
```
to disable advanced permissions
lark-base-role-list.md —
```
+role-list
```
to list roles
lark-base-role-get.md —
```
+role-get
```
to get role details
lark-base-role-create.md —
```
+role-create
```
to create roles
lark-base-role-update.md —
```
+role-update
```
to update roles
lark-base-role-delete.md —
```
+role-delete
```
to delete roles
lark-base-dashboard.md — Dashboard command index (each command has been split into independent documents)
lark-base-dashboard-block.md — Dashboard block command index (each command has been split into independent documents)
dashboard-block-data-config.md — Block data_config structure, chart types, filter rules
lark-base-workflow.md — Workflow command index
lark-base-workflow-schema.md — Detailed explanation of JSON body data structure for
```
+workflow-create/+workflow-update
```
, including configuration rules for triggers and various nodes (highly recommended)
lark-base-data-query.md —
```
+data-query
```
aggregate analysis (DSL structure, supported field types, aggregation functions)
examples.md — Complete operation examples (table creation, import, filter, update)

Command Groups

Mandatory before execution: After locating the command from the table below, be sure to read the corresponding command reference document first, then invoke the command.

Command Group	Description
`table commands`	`+table-list / +table-get / +table-create / +table-update / +table-delete`
`field commands`	`+field-list / +field-get / +field-create / +field-update / +field-delete / +field-search-options`
`record commands`	`+record-list / +record-get / +record-upsert / +record-upload-attachment / +record-delete`
`view commands`	`+view-list / +view-get / +view-create / +view-delete / +view-get-* / +view-set-* / +view-rename`
`data-query commands`	`+data-query`
`history commands`	`+record-history-list`
`base / workspace commands`	`+base-create / +base-get / +base-copy`
`advperm commands`	`+advperm-enable / +advperm-disable`
`role commands`	`+role-list / +role-get / +role-create / +role-update / +role-delete`
`form commands`	`+form-list / +form-get / +form-create / +form-update / +form-delete`
`form questions commands`	`+form-questions-list / +form-questions-create / +form-questions-update / +form-questions-delete`
`workflow commands`	`+workflow-list / +workflow-get / +workflow-create / +workflow-update / +workflow-enable / +workflow-disable`
`dashboard commands`	`+dashboard-list / +dashboard-get / +dashboard-create / +dashboard-update / +dashboard-delete`
`dashboard block commands`	`+dashboard-block-list / +dashboard-block-get / +dashboard-block-create / +dashboard-block-update / +dashboard-block-delete`

lark-base

NPX Install

Tags

SKILL.md Content (Chinese)