lark-base

base

When to use

Use this skill:

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

Do not use this skill:

• For authentication, initialization, identity switching, scope handling, or permission authorization recovery; transfer to lark-shared.
• To import local Excel / CSV / .base files into Base; transfer to lark-drive +import --type bitable.
• For generalized data analysis, field design, or formula discussions without Base/Bitable context.

Usage boundaries

• Base business operations only use the lark-cli base +... shortcut; do not use legacy aggregate commands like +table / +field / +record / +view / +history / +workspace.
• This Base skill does not depend on lark-cli schema. The SKILL only retains routing, risk, and complex JSON/DSL; simple commands are handled by the command's own parameters, tips, and error recovery.
• When a user wants to import Excel / CSV / .base into Base, transfer to lark-cli drive +import --type bitable first, then return to Base commands after the import is complete.
• When a user only provides a Base name or keyword, first use lark-cli drive +search --query <keyword> --doc-types bitable to locate the resource.
• Base commands must have a base_token or a resolvable Base URL first. If there is no token: use +base-create for new ones; search using lark-cli drive +search --query "<base title>" --doc-types bitable --only-title --as user if the user provides a title/keyword; if it still cannot be located, ask the user which specific Base they mean.
• Authentication, initialization, scope, identity switching, and permission recovery belong to lark-shared; the Base documentation only retains permission rules that affect Base path selection.

Quick routing

Base mental model

• Base was formerly known as Bitable; bitable in returned fields, errors, or old documents is mostly for historical compatibility and does not mean you should switch to raw APIs or a different set of commands.
• +base-block-list is the new entry point for viewing a resource directory within a Base: it lists folder/table/docx/dashboard/workflow directly managed by this Base, suitable for determining what is in the Base before deciding to use table, dashboard, workflow, or docx commands.
• base-block is only responsible for resource directory management, including creating resources, moving to folders, renaming, and deleting; specific resource content still uses table/dashboard/workflow commands.
• When creating a new Base, it is highly recommended to execute lark-cli base +base-create --name "<base>" --table-name "<table>" --fields '<field-json-array>' at once, configuring the name and schema of the initial data table in the new Base simultaneously; read lark-base-field-json.md or reuse the field JSON shape from +field-create before using --fields, do not guess field attributes.
• If +base-create is called without --table-name and --fields, it will create an initial data table with a default schema.
• Names and IDs of tables, fields, views, workflows, and dashboard blocks must come from real returns; do not guess based on user descriptions.
• Storage fields are writable; system fields, formula, and lookup are read-only; attachment fields use dedicated attachment commands.
• For one-time raw record queries, prioritize the filter/sort of +record-list / +record-search; for aggregate analysis, prioritize +data-query; only add formula / lookup fields when they need to be displayed in the table long-term.
• 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.
• Read the real structure before writing, analyzing, formulas, lookups, workflows, or dashboards: table, field, view, linked table, and dashboard block names must be based on command returns.
• Cross-table scenarios must read the target table structure; the associated record_id in link cells is just a connection key; the final answer must look up and display user-readable fields.

Identity and permission degradation

• Explicitly use --as user by default to operate on user resources; only use --as bot directly if the user explicitly requests application identity.
• If user identity reports insufficient scope/authorization, or errors contain permission_violations / hint, transfer to lark-shared for user authorization recovery; do not downgrade to bot directly.
• Only retry once with --as bot if user identity reports resource-level access denial without authorization recovery hints; if bot still fails, stop retrying and handle as a permission error.
• Do not loop or switch identities for 91403 or explicit access denial errors.
• If +base-create / +base-copy is executed with bot identity, pay attention to permission_grant in the return and inform the user whether they can open the new Base.

Query and statistical rules

When involving queries, statistics, or conclusions, read lark-base-data-analysis-sop.md and comply with:

1. The default page, fixed --limit, and local jq of +record-list can only prove facts within the read range; they cannot directly support global extremes, total counts, Top/Bottom N, anomaly identification, or grouping conclusions.
2. Filtering, sorting, projection, aggregation, grouping, and limits that can be expressed by Base should be executed in Base cloud query capabilities; do not pull raw records to the local context for manual filtering and sorting.
3. has_more=true or equivalent pagination signals indicate that the current result is not the full set; unless the user only wants samples/first N items, do not answer global questions based on that page.
4. Multi-table queries must first confirm relationship fields and connection keys; the record_id in link cells 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/aggregation conditions, and necessary connection keys.
6. For one-time raw record queries, prioritize the filter/sort of +record-list / +record-search; for aggregate analysis, prioritize +data-query; only consider adding formula / lookup fields if the results need to be displayed in the table long-term.
7. +data-query can return aggregate results or dimension field rows, but dimension rows are deduplicated by field combinations and do not return record_id; use +record-list / +record-search / +record-get to look up individual records, record locations, or full row-level fields.

Writing prerequisites

• Read field structure before writing records; only write to storage fields. System fields, attachment fields, formula, and lookup are not written as normal records.
• Attachment upload, download, and deletion use dedicated +record-*-attachment commands.
• Read lark-base-field-json.md before writing fields; must read formula-field-guide.md / lookup-field-guide.md when involving formula / lookup.
• Table names, field names, view names, and names in workflow configurations must come from real returns; read target table structure in cross-table scenarios.
• High-risk operations such as deletion, role updates, and field updates follow the CLI confirmation gate; use get/list to disambiguate when targets are unclear.
• Batch writes are limited to 200 items per batch; execute serially when writing to the same table, and handle 1254291 by retrying after a short wait.
• +record-batch-update is for "same-value batch updates": the same patch is applied to all record_id_list; do not use it for row-by-row different value mapping.
• Writing unknown options to select/multiselect may trigger the platform to add new options; use +field-list or +field-search-options to confirm available values unless you intend to add new ones.

Form and view details

• Before +form-submit, you must run +form-detail to read questions[].type, required, filter, and the base_token required for attachment scenarios; do not fill in questions hidden by filters.
• Do not write form attachments into fields; place them in --json.attachments; when submitting attachments, you must also pass the --base-token of the Base to which the form belongs.
• +view-set-filter is the only retained view reference; for configurations like sort/group/card/timebar/visible-fields, use the corresponding get command to read the current status, retain unmodified fields, and only replace the configuration the user requested to change.
• Views are suitable for persistence, sharing, and UI reuse; for one-time filtering/sorting, use the filter/sort of +record-list / +record-search to verify results first, then settle into a persistent view as needed.

Tokens and links

If wiki +node-get returns something other than bitable, do not continue using Base commands: transfer docx to document commands, sheet to spreadsheet commands, and other cloud space objects to corresponding skills or drive.

Dashboard / Workflow / Role

• The complexity of Dashboards lies in the data_config of blocks, not in list/get/create/delete command parameters. Read dashboard-block-data-config.md before creating or updating blocks; components must be created serially; +dashboard-arrange is server-side intelligent layout, only execute when the user explicitly requests rearrangement/beautification. +dashboard-block-get-data reads the final calculation result of a chart and does not return block name, type, layout, or data_config; use +dashboard-block-get for metadata.
• The complexity of Workflows lies in the steps structure. Read the entry lark-base-workflow-guide.md and steps JSON SSOT lark-base-workflow-schema.md when creating, updating, or interpreting a full workflow; enable/disable/list only require confirming workflow ID, current status, and user intent.
• The complexity of Roles lies in the permission JSON. Read the entry lark-base-role-guide.md for role operations; +role-create only supports custom roles; +role-update is a delta merge; read permission JSON SSOT role-config.md when creating/updating roles or interpreting full configurations. +role-delete only applies to custom roles; system roles cannot be deleted; confirm targets and impact before deleting roles or disabling advanced permissions.

Common recovery

Retained References

• lark-base-data-analysis-sop.md: SOP for query/statistics/global conclusion routing
• lark-base-data-query-guide.md / lark-base-data-query.md: Aggregate query entry fewshot and DSL SSOT
• lark-base-cell-value.md: Record CellValue construction
• lark-base-field-json.md: Field JSON construction
• formula-field-guide.md / lookup-field-guide.md: Formula and lookup fields
• lark-base-field-create.md / lark-base-field-update.md: Field creation/update command-level supplements
• lark-base-record-upsert.md / lark-base-record-batch-create.md / lark-base-record-batch-update.md / lark-base-record-history-list.md: Record writing JSON and history return interpretation
• lark-base-view-set-filter.md: View filter JSON
• lark-base-form-detail.md / lark-base-form-submit.md / lark-base-form-questions-create.md / lark-base-form-questions-update.md: Form details, submission, and complex JSON
• lark-base-dashboard.md / dashboard-block-data-config.md / lark-base-dashboard-block-get-data.md: Dashboard, component configuration, and chart result protocol
• lark-base-workflow-guide.md / lark-base-workflow-schema.md: Workflow entry and steps JSON SSOT
• lark-base-role-guide.md / role-config.md: Role entry and permission JSON SSOT