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

lark-base

Office & productivity

View repository

Updated 10-15 16:45

About this skill

base

When to use

Use this skill:

  • The user explicitly mentions Base / bitable, or provides a /base/ link.
  • The user wants to create tables, modify tables, manage fields, write records, query records, or configure views within Base.
  • The user wants to do formula fields, lookup fields, cross-table calculations, derived metrics, filter aggregation, TopN, or statistical analysis within Base.
  • The user wants to manage Base forms, dashboards, workflow, advanced permissions, or roles.
  • The user wants to migrate old Base aggregate-style commands or old syntax to the current lark-cli base +... shortcut。

Do not use this skill:

  • For authentication, initialization configuration, identity switching, handling scope, or permission authorization recovery only, go to lark-shared。
  • To import local Excel / CSV / .base into Base, go to lark-drive +import --type bitable。
  • For generalized data analysis, field design, or formula discussion, but without Base/bitable context.

Usage boundaries

  • Base business operations only use lark-cli base +... shortcut, not the old aggregate-style +table / +field / +record / +view / +history / +workspace。
  • This round of Base does not depend on lark-cli schema. The SKILL only retains routing, risks, and complex JSON/DSL; simple commands are handled by the command's own parameters, tips, and error recovery.
  • When the user wants to import Excel / CSV / .base into Base, first go to lark-cli drive +import --type bitable, and after the import is complete, return to the Base command.
  • Authentication, initialization, scope, identity switching, and insufficient permission recovery belong to lark-shared; Base documentation only retains permission rules that affect Base path selection.

First obtain the Base Token and required IDs

Before entering any shortcut that requires a target Base, you must first obtain a usable base_token, as well as the table_id / view_id / record_id / form_id / dashboard_id / workflow_id and other real IDs needed for the current task; do not treat a full URL, wiki token, workspace token, or isolated raw token directly as --base-token。

  • The user inputs a URL or share link: first run lark-cli base +url-resolve --url "<url>" --as user, and use the returned base_token and related IDs to continue with subsequent commands.
  • The user inputs a Base title, keyword, or uncertain name: first run lark-cli base +title-resolve --title "<keyword>" --as user；--title passing a short keyword from the title, no more than 30 characters; for overly long titles, first take the most distinctive short keyword; when there are multiple candidates, first let the user disambiguate, do not guess.
  • Document embeds a Base tag: directly read <bitable> / <base_refer> of token as --base-token，table-id as --table-id，view-id as --view-id; an isolated raw token does not go through +url-resolve。
  • If it still cannot be located and the user is not trying to create a new Base, first ask the user which Base they want to operate on; only when the user wants to create a new one, use +base-create。

Quick routing

User goal Preferred command When to read reference
Query the Base itself +base-get Use the return to confirm the Base name, owner, permissions, and the token for continued operations
Create/copy Base +base-create / +base-copy When creating, strongly recommend using --table-name + --fields to simultaneously configure the name and schema of the only initial data table in the new Base; after writing, report the new Base identifier and permission_grant
View the resource directory within the Base +base-block-list Use this first when you want to know which table/docx/dashboard/workflow/folder are in a Base; return ID relationships and fewshot see --help
Manage the resource directory within a Base +base-block-create/move/rename/delete Create or organize folder/table/docx/dashboard/workflow directly managed by the Base; continue using the corresponding commands for resource content
Manage data tables +table-list/get/create/update/delete Handle listing, details, creation, renaming, and deletion of tables
List/get/delete fields +field-list/get/delete/search-options Before writing, use list/get to confirm field type, options, and ID; before deleting, confirm the target field
Create/update fields +field-create / +field-update Required reading lark-base-field-json.md; for formulas read formula-field-guide.md; for lookup read lookup-field-guide.md; for command details read lark-base-field-create.md / lark-base-field-update.md
Read record details +record-get / +record-list / +record-search When involving filtering, sorting, Top/Bottom N, aggregation, multi-table joins, or global conclusions, read lark-base-data-analysis-sop.md
Write records +record-upsert / +record-batch-create / +record-batch-update Required reading lark-base-record-upsert.md / lark-base-record-batch-create.md / lark-base-record-batch-update.md and lark-base-cell-value.md
Attachment fields +record-upload-attachment / +record-download-attachment / +record-remove-attachment Do not fake attachments as ordinary CellValue; upload from local files, download/delete by file token or field location
Delete records / share record links / history +record-delete / +record-share-link-create / +record-history-list Confirm record before deletion; shared links are limited to 100; for history read lark-base-record-history-list.md, only query a single record, do not perform whole-table auditing
Manage views +view-* +view-set-filter read lark-base-view-set-filter.md; for other configurations, first get the current state, then update according to the returned structure
One-time aggregate statistics +data-query Required reading lark-base-data-analysis-sop.md and entry lark-base-data-query-guide.md; for the complete DSL read lark-base-data-query.md
Formula fields +field-create/update --json '{"type":"formula",...}' Required reading formula-field-guide.md, after reading add the hidden confirmation flag --i-have-read-guide
Lookup fields +field-create/update --json '{"type":"lookup",...}' Required reading lookup-field-guide.md, after reading add the hidden confirmation flag --i-have-read-guide
Form submission +form-submit First read lark-base-form-detail.md to get the questions, filter, and what is needed for attachments base_token; for submitting JSON read lark-base-form-submit.md
Create/update form questions +form-questions-create / +form-questions-update Read lark-base-form-questions-create.md / lark-base-form-questions-update.md
Other form management +form-list/get/detail/create/update/delete / +form-questions-list/delete +form-detail read lark-base-form-detail.md; before deleting, confirm the target form
Dashboards and components +dashboard-* / +dashboard-block-* When charts/boards/blocks are mentioned, first read lark-base-dashboard.md; for components data_config read dashboard-block-data-config.md; to read chart calculation results use +dashboard-block-get-data
Workflow +workflow-* When creating/updating or understanding steps, read the entry lark-base-workflow-guide.md and the steps JSON SSOT lark-base-workflow-schema.md; list/get/enable/disable only handle workflow ID and enabled/disabled status
Advanced permissions and roles +advperm-* / +role-* For role operations, first read the entry lark-base-role-guide.md; for role create/update or interpreting the complete configuration, then read the permissions JSON SSOT role-config.md; system roles cannot be deleted; disabling advanced permissions will affect custom roles

Base mental model

  • Base was formerly named Bitable; in returned fields, errors, or old documents, bitable is mostly historical compatibility and does not mean you should switch to the raw API or another set of commands.
  • +base-block-list is the new entry point for viewing the resource directory within a Base: it lists what this Base directly manages folder/table/docx/dashboard/workflow, suitable for first determining what is in the Base, then deciding to use table, dashboard, workflow, or docx commands.
  • base-block Only responsible for resource directory management, including creating resources, moving to a folder, renaming, and deleting; specific resource content still goes through the table/dashboard/workflow commands.
  • When creating a new Base, it is strongly recommended to execute in one go lark-cli base +base-create --name "<base>" --table-name "<table>" --fields '<field-json-array>', and at the same time configure the name and schema of the only initial data table in the new Base; before using --fields , first read lark-base-field-json.md or reuse the field JSON shape of +field-create , do not guess field attributes.
  • +base-create When not passing --table-name and --fields , an initial data table with a default schema will be created.
  • The names and IDs of tables, fields, views, workflows, and dashboard blocks must come from actual returns; do not guess based on what the user says.
  • Storage fields are writable; system fields,formula、lookup are read-only; attachment fields go through the dedicated attachment command.
  • For one-off raw record queries, prefer the filter/sort of +record-list / +record-search ; for aggregate analysis, prefer +data-query; only when it needs to be displayed in the table long-term, add a formula / lookup field.
  • formula is suitable for routine calculations, conditional judgments, text/date processing, and long-term derived metrics;lookup is suitable for explicit cross-table lookups, value retrieval after filtering, or aggregate references.
  • Before writing, analysis, formulas, lookup, workflow, or dashboard, first read the actual structure: table, field, view, linked table, and dashboard block names are all based on command returns.
  • Cross-table scenarios must read the target table structure; the linked record_id in a link cell is only a join key, and the final answer must look it up and display a user-readable field.

Identity and Permission Downgrade

  • By default, explicitly use --as user to operate on user resources; only when the user explicitly requests the app identity, directly use --as bot。
  • If the user identity reports insufficient scope/authorization, or the error contains permission_violations / hint, first switch to lark-shared to restore user authorization; do not directly downgrade to bot.
  • Only when the user identity reports no access at the resource level and there is no authorization recovery prompt, may you use --as bot to retry once; if bot still fails, stop retrying and handle it as a permission error.
  • 91403 or explicit inaccessible errors, do not loop through identity switching and retry.
  • +base-create / +base-copy If executing with the bot identity, pay attention to the permission_grantin the return, and inform the user whether they can open the new Base.

Query and Statistics Rules

When queries, statistics, or judgment conclusions are involved, first read lark-base-data-analysis-sop.md, and comply with:

  1. +record-list The default page, fixed --limit , and local jq can only prove facts within the range already read, and cannot directly support global extremes, full counts, Top/Bottom N, anomaly identification, or grouping conclusions.
  2. Filtering, sorting, projection, aggregation, grouping, and limits that can be expressed by the Base should be executed in the Base cloud query capability; do not first pull raw records into the local context and then manually filter and sort.
  3. has_more=true or an equivalent pagination signal indicates that the current result is not the full set; unless the user only wants a sample/first N records, you cannot answer a global question based on that page.
  4. Multi-table queries must first confirm the relationship field and join key; the record_id in a link cell is a relationship key, not a user-readable answer.
  5. The final answer must be traceable to the real table, real fields, query scope, filter/sort/aggregate conditions, and necessary join keys.
  6. For one-off raw record queries, prefer the filter/sort of +record-list / +record-search ; for aggregate analysis, prefer +data-query; only consider adding a formula / lookup field if the result needs to be displayed in the table long term.
  7. +data-query can return aggregated results or dimension field rows, but dimension rows are deduplicated by field combination and do not return record_id; when you need record-by-record details, record location, or complete row-level fields, use +record-list / +record-search / +record-get to query back.

Pre-write rules

  • Before writing records, first read the field structure; only write storage fields. System fields, attachment fields, andformula、lookup are not targets for writing as ordinary records.
  • Attachment upload, download, and delete go through the dedicated +record-*-attachment commands.
  • Before writing fields, first read lark-base-field-json.md; when formula / lookup is involved, you must read formula-field-guide.md / lookup-field-guide.md。
  • Table names, field names, view names, and names in workflow configuration must come from actual returned results; in cross-table scenarios, also read the target table structure.
  • High-risk operations such as deletion, role updates, and field updates follow the CLI's confirmation gate; when the target is unclear, first use get/list to disambiguate.
  • Batch writes are limited to a maximum of 200 records per batch; when writing to the same table consecutively, execute serially, and when encountering 1254291 , handle it by briefly waiting and then retrying.
  • +record-batch-update is a "same-value batch update": the same patch is applied to all record_id_list; do not use it for per-row different-value mapping.
  • Writing unknown options to select/multiselect may trigger the platform to add new options; if you do not intend to add new options, first use +field-list or +field-search-options to confirm the available values.

Form and view details

  • +form-submit Before that, you must first run +form-detail, read questions[].type、required、filter and the base_tokenneeded for attachment scenarios; do not fill in questions hidden by filter.
  • Do not write form attachments into fields, put them in --json.attachments; when submitting attachments, you must also pass the form's owning Base's --base-token。
  • +view-set-filter is the only retained view reference; for configurations such as sort/group/card/timebar/visible-fields, first use the corresponding get command to read the current state, retain unmodified fields, and only replace the configuration the user requested to change.
  • Views are suitable for persistence, sharing, and UI reuse; for one-off filtering/sorting, you can first use +record-list / +record-search 's filter/sort to verify the results, then persist it as a view as needed.

Dashboard / Workflow / Role

  • The complex part of a Dashboard is the block's data_config, not the list/get/create/delete command parameters. Before creating or updating a block, first read dashboard-block-data-config.md; components must be created serially;+dashboard-arrange is server-side intelligent layout, and is only executed when the user explicitly requests rearrangement/beautification.+dashboard-block-get-data Reads the chart's final computed results, and does not return the block name, type, layout, or data_config; if metadata is needed, first use +dashboard-block-get。
  • The complex part of a Workflow is the steps structure. When creating, updating, or explaining a complete workflow, read the entry point lark-base-workflow-guide.md and the steps JSON SSOT lark-base-workflow-schema.md; enable/disable/list only need to confirm the workflow ID, current enabled/disabled state, and user intent.
  • The complex part of a Role is the permission JSON. For role operations, first read the entry point lark-base-role-guide.md；+role-create only supports custom roles;+role-update is a delta merge; when creating/updating a role or interpreting a complete configuration, read the permission JSON SSOT role-config.md。+role-delete only applies to custom roles, system roles cannot be deleted; before deleting a role and disabling advanced permissions, you must confirm the target and impact.

Common recovery

Error / Symptom Recovery action
param baseToken is invalid / base_token invalid Check whether a wiki token, workspace token, or full URL was mistaken for --base-token; follow the entry rules to re-obtain the real base_token
not found and the input comes from a Wiki link First check whether a wiki token was mistaken for a base token; do not immediately switch to the raw API
1254045 field name does not exist Re- +field-list, using the real field name or field ID; pay attention to spaces, case, and cross-table fields
1254015 field value type mismatch First +field-list, then follow lark-base-cell-value.md to construct the CellValue
Date / person / hyperlink field reports a format error For dates use YYYY-MM-DD HH:mm:ss; for people use [{ "id": "ou_xxx" }]; for hyperlinks use a URL or markdown link string
formula / lookup creation failed First read formula-field-guide.md / lookup-field-guide.md, then rebuild the request according to the guide
ignored_fields / READONLY Remove read-only fields and write only storage fields
1254104 The batch exceeds 200; call in batches
1254291 Concurrent write conflict; write serially and wait briefly between batches
91403 No permission to access this Base; handle according to the lark-shared permission process; do not blindly retry

Keep the Reference