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

1. 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

2. 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
3. Formula / lookup have hard thresholds
   • Read the corresponding guide first
   • After reading the guide, create the corresponding field
4. 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

1. 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.
2. 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

   .
3. 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

1. 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.
2. 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.
3. 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.
4. 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

1. When involving formula / lookup, read the guide first, then write commands
   • formula:

     formula-field-guide.md

   • lookup:

     lookup-field-guide.md

2. 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
3. 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.
4. 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.
5. 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

1. 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
2. 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

1. 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

2. 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
3. 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

4. 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

5. 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

6. 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

7. 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
8. 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
9. Unified parameter name — Always use

   --base-token

   , do not use the old

   --app-token

10. 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

11. 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
12. 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

lark-cli base +table-list

+table-get

lark-cli base +table-create

+table-update

+table-delete

lark-cli base +field-list

+field-get

lark-cli base +field-create

+field-update

--json

lark-cli base +field-create

+field-update

type=formula

lark-cli base +field-create

+field-update

type=lookup

lark-cli base +record-list

+record-get

aggregate calculation

group statistics

+data-query

lark-cli base +record-upsert

--table-id [--record-id] --json

lark-cli base +data-query

+record-list

+data-query

lark-cli base +view-*

list/get/create/delete/get-*/set-*/rename

lark-cli base +record-history-list

lark-cli base +view-set-filter

lark-cli base +record-list

lark-cli base +base-create

+base-get

+base-copy

lark-cli base +workflow-list

+workflow-get

lark-cli base +workflow-create

+workflow-update

--json

lark-cli base +workflow-enable

+workflow-disable

lark-cli base +advperm-enable

+advperm-disable

lark-cli base +role-list / +role-get

lark-cli base +role-create / +role-update / +role-delete

lark-cli base +form-list

+form-get

lark-cli base +form-create

+form-update

+form-delete

lark-cli base +form-questions-list

+form-questions-create

+form-questions-update

+form-questions-delete

lark-cli base +dashboard-list

+dashboard-get

lark-cli base +dashboard-create

+dashboard-update

+dashboard-delete

lark-cli base +dashboard-block-list

+dashboard-block-get

lark-cli base +dashboard-block-create

+dashboard-block-update

+dashboard-block-delete

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!)

/wiki/TOKEN

Processing Flow

1. Query node information using

   wiki.spaces.get_node

   bash

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

2. 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
3. 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.*

   |
4. 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

     .
5. 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

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

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

Base Link Parsing Rules

/base/{token}

--base-token

/wiki/{token}

wiki.spaces.get_node

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

{text, link}

[{id:"ou_xxx"}]

user_id_type

+field-list

param baseToken is invalid

base_token invalid

base_token

/wiki/...

wiki_token

lark-cli wiki spaces get_node

obj_token

obj_type=bitable

node.obj_token

--base-token

bitable/v1

formula-field-guide.md

lookup-field-guide.md

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.

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