SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslark-base

lark-base

Design & creation

View repository

Updated 10-15 23:59

About this skill

base

Prerequisites: First read ../lark-shared/SKILL.md。 Before execution, you must: Before executing any base command, you must first read the reference documentation for the corresponding command, then call the command. Naming convention: Use only lark-cli base +... command forms.

Agent Quick Execution Order

  1. First determine the task type
    • Temporary statistics / aggregation analysis → +data-query
    • To display results in the table long-term → formula field
    • When the user explicitly wants lookup, or it is indeed more suitable for from/select/where/aggregate → lookup field
    • Detail reading / export → +record-list / +record-get
  2. Get the structure first, then write the command
    • At minimum, first get the current table structure:+field-list or +table-get
    • For cross-table scenarios, you must also querythe target table's structure
  3. formula / lookup have hard requirements
    • First read the corresponding guide
    • After reading the guide, then create the corresponding field
  4. Determine field writability before writing records
    • Only write storage fields
    • System fields / formula / lookup are read-only by default

Prohibited Agent Behaviors

  • Do not treat +record-list as an aggregation analysis engine
  • Do not create formula / lookup fields directly without reading the guide
  • Do not guess table names, field names, or field references in formula expressions based on natural language
  • Do not treat system fields, formula fields, or lookup fields as +record-upsert write targets
  • Do not switch to lark-cli api GET /open-apis/bitable/v1/...
  • Do not, because of the obj_type=bitable in the wiki parsing result, go look for bitable.*; in this CLI you should continue to use lark-cli base +...

Base Basic Mental Model

  1. Base fields fall into three categories
    • Storage fields: store data actually entered by users, usually suitable for +record-upsert writing, such as text, number, date, single select, multi-select, person, and link.Attachment fields are the exception: for agents, file uploads must go through +record-upload-attachment。
    • System fields: automatically maintained by the platform, read-only, typically including creation time, last update time, creator, modifier, and auto-number.
    • Calculated fields: derived through expressions or cross-table rules, read-only, typically including formula fields (formula) and lookup reference fields (lookup)。
  2. Determine the field category before writing records — only storage fields can be written directly; formula / lookup / creation time / update time / creator / modifier / auto-number should all be regarded as read-only output fields and cannot be used as +record-upsert input parameters.
  3. Base is not only for storing table data; it can also have built-in calculations — When users request things like "statistics, comparison, ranking, text concatenation, date difference, cross-table aggregation, status judgment", do not default to exporting data and calculating manually; first determine whether it should be done through +data-query or formula fields within Base.

Analysis Path Decision

  1. One-off analysis / ad-hoc query → Prefer +data-query
    • Suitable for: grouped statistics, SUM / AVG / COUNT / MAX / MIN, aggregation after conditional filtering.
    • Characteristics: what is wanted is "the result calculated this time", not precipitating the result into a field within the table.
  2. Long-term reusable derived metrics / row-level calculation results → Prefer formula fields
    • Suitable for: profit margin, whether overdue, remaining days, tier labels, derived results after cross-table aggregation.
    • Characteristics: the result needs to be displayed in Base long-term and update automatically with records.
  3. Explicitly requires Lookup, or genuinely needs to be modeled by source/select/where/aggregate → Use lookup field
    • By default still prioritize formula. Use lookup only when the user explicitly requests it, or when it better fits a fixed lookup configuration.
  4. Raw record reading / detail export → +record-list / +record-get
    • Do not treat +record-list as an analysis engine; it is responsible for fetching details, not for aggregation calculations.

Formula / Lookup Special Rules

  1. When formula / lookup is involved, read the guide first, then issue the command
  2. Guide before creation command
    • Before reading the corresponding guide, do not directly create formula / lookup fields
    • After reading the guide, then complete the corresponding JSON and create the field
    • type=formula must provide expression
    • type=lookup must provide from / select / where, supplement with aggregate
  3. Formula fields take precedence over lookup fields
    • As long as the user's request is "calculation / conditional judgment / text processing / date difference / cross-table aggregation / value retrieval after cross-table filtering", by default prioritize trying formula.
    • Only when the user explicitly says lookup, or when the configuration is naturally more suitable for the lookup quadruple, then use lookup.
  4. Table names / field names must match exactly
    • Table names / field names appearing in formulas, lookup, and data-query must come from +table-list / +table-get / +field-list actual returns; it is forbidden to guess and rewrite based on semantics.
  5. Get the structure first, then write the expression
    • For formulas or lookup, always obtain the relevant table structure first, then generate the expression / configuration; do not directly piece together field names based on the user's verbal description.

Workflow Special Rules

  1. Before executing any workflow command, you must first read two documents: the corresponding command document + lark-base-workflow-schema.md

  2. Confirm dependency information before creation

    • First, through +table-list / +field-list obtain the real table names and field names
    • Do not guess table names/field names from natural language and fill them into the workflow configuration

Core Rules

  1. Use only atomic commands — Use +table-list / +table-get / +field-create / +record-upsert / +view-set-filter / +record-history-list / +base-get this one-command-one-action style, do not use the old aggregate-style +table / +field / +record / +view / +history / +workspace
  2. Read the field structure before writing records — First call +field-list to get the field structure, then read lark-base-shortcut-record-value.md to confirm the write value format for each field type
  3. Check the field property specification before writing fields — First read lark-base-shortcut-field-properties.md to confirm +field-create/+field-update JSON structure
  4. Execute filtered queries according to view capabilities — First read lark-base-view-set-filter.md and lark-base-record-list.md, and complete the filtered read through the +view-set-filter + +record-list combination
  5. Analyze records (involving analysis intents such as "highest/lowest/total/average/ranking/comparison/count") — First read lark-base-data-query.md, and use +data-query for server-side computation of data filtering and aggregation
  6. Aggregate analysis and data retrieval are mutually exclusive — When grouped statistics / SUM / MAX / AVG / COUNT are needed, you must use +data-query(server-side computation), and it is forbidden to use +record-list to pull all records and then calculate manually; conversely,+data-query does not return raw records, and data retrieval scenarios still use +record-list / +record-get
  7. All +xxx-list concurrent calls are forbidden — +table-list / +field-list / +record-list / +view-list / +record-history-list / +role-list can only be executed serially
  8. Batch limit 500 records per call — For the same table, serial writes are recommended, with a 0.5–1 second delay between batches
  9. Unified parameter names — Always use --base-token, do not use the old --app-token
  10. When encountering requirements for "formulas / lookup references / derived metrics / cross-table calculations", prioritize the field solution judgment — First determine whether a formula / lookup field should be created, or only a one-time +data-query
  11. Formula, lookup, and system fields are considered read-only by default — Except for +field-create / +field-update maintaining field definitions, do not use these fields as record write targets
  12. Execute renaming and deletion according to explicit intent — +view-rename can be executed directly when both the target view and the new name are clear;+record-delete / +field-delete / +table-delete can also be executed directly when the user has explicitly requested deletion and the target is clear, without needing another confirmation, and when executing the delete command, proactively add --yes; only continue asking when the target is unclear

Questionnaire / Form Tips

  • Get questionnaire list: Use +form-list(first get form-id）
  • Get a 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 Notes
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 command, one action
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 the formula guide first, then create/update
Create/update lookup field lark-cli base +field-create / +field-update type=lookup; read the lookup guide first, then create/update; by default first determine whether formula is more appropriate
List/get records lark-cli base +record-list / +record-get atomic command, if needed聚合计算，分组统计 recommended to use +data-query
Create/update records lark-cli base +record-upsert --table-id [--record-id] --json
Aggregate analysis/comparison sorting/find extreme values/filter statistics lark-cli base +data-query Do not use +record-list to pull all data and then calculate manually; use +data-query for server-side computation
Configure/query views lark-cli base +view-* list/get/create/delete/get-*/set-*/rename
View record history lark-cli base +record-history-list Query change 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 workflow lark-cli base +workflow-create / +workflow-update Use --json, must read the schema
Enable/disable workflow lark-cli base +workflow-enable / +workflow-disable one command, one action
Enable/disable advanced permissions lark-cli base +advperm-enable / +advperm-disable Custom roles can only be used after enabling; disabling will invalidate existing roles
List/get roles lark-cli base +role-list / +role-get View role summary or full 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 command, one action
List/create/update/delete form questions lark-cli base +form-questions-list / +form-questions-create / +form-questions-update / +form-questions-delete one command, one action
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 command, one action
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 command, one action

Operational notes

  • Unified Base token convention: uniformly use --base-token
  • +xxx-list Call discipline：+table-list / +field-list / +record-list / +view-list / +record-history-list / +role-list / +dashboard-list / +dashboard-block-list / +workflow-list Concurrent calls are prohibited; batch execution can only be serial
  • +record-list limit upper bound：--limit maximum 200. When more data is needed, pagination must be used (offset increment) to pull in batches; passing more than 200
  • Determine field writability first: only stored fields are writable; formula/lookup/system fields are read-only by default and should be skipped when writing records
  • Proactively consider formula capabilities: when the user says "calculate", "generate tags", "determine whether abnormal", "cross-table summary", or "alert based on date difference", first determine whether a formula field should be created, rather than only returning a manual analysis plan
  • lookup is not the default first choice: lookup is used only when the user explicitly requests it or when it is indeed more suitable for a fixed lookup model; for regular calculations, cross-table aggregations, and conditional judgments, prefer formula
  • Attachment fields: if the user wants to "upload attachments/add files to records", only use +record-upload-attachment This chain (read field → read record → upload asset → write back record)
  • Person field / user field: When debugging, pay attention to user_id_type and the difference in execution identity (user / bot)
  • How to use history：+record-history-list Query record history by table-id + record-id ; full-table history scanning is not supported
  • workspace status: Already integrated +base-create / +base-get / +base-copy
  • +base-create / +base-copy Result return specification: After successful creation or copy, the reply must proactively return the identifier information of the new Base. If the returned result includes an accessible link (such as base.url), return it as well
  • +base-create / +base-copy Friendliness rules：--folder-token、--time-zone, and --name during copy are all optional. When the user has no special requirements, do not interrupt extra for these optional parameters; if you can create/copy directly, just execute directly
  • +base-create / +base-copy Permission handling (bot creation): If the Base is created by an application identity (bot), after successful creation or copy, by default continue using the bot identity to add full_access(admin) permission for the currently available user (referring to the user identity that is logged in and available in the auth module of the current CLI), and clearly state the authorization result in the reply (success / no available user / authorization failed and the reason). If authorization is not completed, continue to provide follow-up guidance (retry authorization later or continue using the bot); owner transfer must be confirmed separately, and unauthorized execution is prohibited
  • How to use dashboard：+dashboard-create Return after creation dashboard_id; Block's data_config is passed in as a JSON string, supporting @file.json to read files
  • How to use advperm：+advperm-enable Roles can only be managed after enabling advanced permissions (+role-*）；+advperm-disable is a high-risk operation; after disabling, all existing custom roles become invalid; the operating user must be a Base admin; first read lark-base-advperm-enable.md / lark-base-advperm-disable.md
  • How to use role：+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); before writing a role, first read role-config.md
  • Form form-id: Obtained via +form-list ;+form-create returned id is form-id, which can be used for +form-questions-* operations
  • How to use workflow: 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; at the same time, +workflow-list does not return a complete tree structure. If you need to read the complete structure, please use +workflow-get。
  • How to use data-query: Before using +data-query , you must first read lark-base-data-query.md to understand the DSL structure, supported field types, aggregate functions, and constraints; the field_name in the DSL must exactly match the table field names. Before constructing, first use +field-list to obtain the real field names
  • How to use formulas / lookup: Before constructing expressions or where conditions, at least first obtain the current table structure; when crossing tables, look up the structure of the target table. It is not allowed to guess field names from natural language
  • View rename confirmation rule: When the user has clearly specified "which view to rename to what",+view-rename just execute it directly; no additional confirmation is needed
  • Deletion confirmation rules (records / fields / tables): If the user has clearly stated they want to delete, and the target is also clear,+record-delete / +field-delete / +table-delete you can execute directly without another confirmation; when executing, directly include --yes to pass the CLI's high-risk write validation. Only when the target is still ambiguous, first use +record-get / +field-get / +table-get or the list command to confirm

Special handling for Wiki links (especially critical!)

A knowledge base link (/wiki/TOKEN) may point to different types of documents such as cloud docs, spreadsheets, or bitables.Do not directly assume that the token in the URL is the file_token; you must first query the actual type and the real token.

Processing flow

  1. Use wiki.spaces.get_node to query node information

    lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}'

  2. Extract key information from the returned result

    • node.obj_type: document type (docx/doc/sheet/bitable/slides/file/mindnote)
    • node.obj_token：the real document token(used for subsequent operations)
    • node.title: document title

  3. Based on obj_type , choose the subsequent command

    | obj_type | Description | Subsequent command | |----------|------|-----------| | docx | New cloud doc | drive file.comments.*、docx.* | | doc | Old cloud doc | drive file.comments.* | | sheet | Spreadsheet | sheets.* | | bitable | Bitable | lark-cli base +...(preferred); if shortcut does not cover it, then use lark-cli base <resource> <method>；Do notswitch to lark-cli api /open-apis/bitable/v1/... | | slides | Slides | drive.* | | file | File | drive.* | | mindnote | Mind map | drive.* |

  4. Use the obj_token resolved from the wiki as the Base token

    • When obj_type=bitable ,node.obj_token is the real token that subsequent base commands should use.
    • In other words: if the original input is a /wiki/... link, do not pass wiki_token directly to --base-token。

  5. If a token error has already been reported, go back and check the wiki

    • If the command returns param baseToken is invalid、base_token invalid、not found, and what the user originally provided was a /wiki/... link or wiki_token, first suspect "the wiki token was treated as a base token".
    • At this point, do not switch to the bitable/v1 API; immediately re-run lark-cli wiki spaces get_node, confirm obj_type=bitable , then switch to node.obj_token to re-run lark-cli base +...。

Query example

# 查询 wiki 节点
lark-cli wiki spaces get_node --params '{"token":"Pgrr***************UnRb"}'

Example returned result:

{
  "node": {
    "obj_type": "docx",
    "obj_token": "UAJ***************E9nic",
    "title": "ai friendly 测试 - 1 副本",
    "node_type": "origin",
    "space_id": "6946843325487906839"
  }
}

Base link parsing rules

Link type Format Handling method
Direct Base link /base/{token} Directly extract as --base-token
Wiki knowledge base link /wiki/{token} First call wiki.spaces.get_node, 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

  • ProhibitedPassing the complete URL directly as the --base-token parameter
  • ProhibitedPassing the wiki_token directly as the --base-token

Common error quick reference

Error code Meaning Solutions
1254064 Incorrect date format Use a millisecond timestamp, not a string / second-level
1254068 Incorrect hyperlink format Use a {text, link} object
1254066 Incorrect person field Use [{id:"ou_xxx"}], and confirm user_id_type
1254045 Field name does not exist Check the field name (including spaces and case)
1254015 Field value type mismatch First +field-list, then construct according to the type
param baseToken is invalid / base_token invalid A wiki token, workspace token, or other token was mistaken for a base_token If the input comes from /wiki/..., first use lark-cli wiki spaces get_node to get the real obj_token; when obj_type=bitable , use node.obj_token as the --base-token and retry; do not switch to bitable/v1
formula / lookup creation failed Guide not read or structure invalid First read formula-field-guide.md / lookup-field-guide.md, then rebuild the request according to the guide
Failed to write system field / formula field A read-only field was treated as a writable field Write to a storage field instead; leave the computed result to be produced automatically by formula / lookup / system fields
1254104 Batch exceeds 500 records Call in batches
1254291 Concurrent write conflict Serial writes + delay between batches

Reference documentation

Command groupings

Must do before execution: After locating the command from the table below, be sure to read the reference documentation for the corresponding command before calling the command.

Command groupings 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