base

base

Interact with Lark Base spreadsheets and databases through the Lark API

Category: design Source: larksuite/cli

base: Interact with Lark Base Spreadsheets and Databases through the Lark API

The base skill (lark-base) on the Happycapy Skills platform enables powerful and structured automation when working with Lark Base (Feishu Base) spreadsheets and databases. By leveraging the Lark API via the official lark-cli tool, users can perform a wide range of operations including table creation, field management, record manipulation, view configuration, historical queries, and administrative tasks such as managing roles, forms, and dashboards. This article explains the capabilities, recommended usage, and best practices for the base skill.

What Is This Skill?

lark-base is a command-line skill that provides programmatic access to Lark Base. It is designed to work exclusively with the official lark-cli tool, abstracting complex API calls into a series of structured lark-cli base +... commands. This skill supports operations such as:

  • Creating and managing tables and fields
  • Reading and writing records
  • Configuring views
  • Querying record histories
  • Handling formulas, lookups, and cross-table calculations
  • Managing roles, forms, and dashboards

The skill is particularly tailored for scenarios involving field design, formula fields, lookup references, cross-table calculations, row-level derived metrics, and data analysis requirements.

Why Use lark-base?

Lark Base is a versatile platform for organizing and analyzing structured data. However, direct API integration or manual UI operations can be cumbersome for repetitive or complex workflows. The lark-base skill provides several advantages:

  • Consistency: Enforces standardized command patterns (lark-cli base +...), reducing the risk of errors.
  • Automation: Enables scripts and bots to reliably manipulate Base data without manual intervention.
  • Data Integrity: Protects against accidental writes to read-only or system fields.
  • Best Practices: Embeds guardrails, such as requiring users to consult reference guides before performing complex operations (e.g., formulas or lookups).
  • Extensibility: Supports advanced use cases like cross-table analytics and data aggregation.

How to Use lark-base

Prerequisites

  • Ensure lark-cli is installed and configured.
  • Review the shared skill documentation referenced in lark-shared/SKILL.md.
  • Always consult the relevant command reference documentation before executing any base command.

Basic Command Structure

All commands follow the convention:

lark-cli base +<subcommand> [options]

Common Operations

  1. Determine Task Type

    • For ad-hoc statistics or aggregation: use +data-query.
    • To persist computed results in a table: use formula fields.
    • For lookups or cross-table operations: use lookup fields.
    • For detailed read/export: use +record-list or +record-get.

  2. Inspect Table Structure First

    Before any operation, fetch the table structure to ensure accuracy:

    lark-cli base +field-list --table-id=<TABLE_ID>

    For cross-table scenarios, inspect both source and target tables.

  3. Create Formula or Lookup Fields

    • Always consult the guide before creating these fields.

    • Example (after guide review):

      lark-cli base +field-create --table-id=<TABLE_ID> --type=formula --name="Total" --formula="Price * Quantity"

  4. Write Records

    • Only write to storage fields (text, number, date, single-select, multi-select, etc).

    • Example:

      lark-cli base +record-upsert --table-id=<TABLE_ID> --fields='{"Name":"Alice","Amount":100}'

    • For file uploads (attachments), use:

      lark-cli base +record-upload-attachment --table-id=<TABLE_ID> --record-id=<RECORD_ID> --file=./invoice.pdf

  5. Read or Export Records

    lark-cli base +record-list --table-id=<TABLE_ID> --view-id=<VIEW_ID>

Prohibited Behaviors

  • Do not use +record-list for aggregation or analytics - use +data-query.
  • Never create formula or lookup fields without first reading the guide.
  • Do not guess table or field names or reference fields in formulas by intuition.
  • Never attempt to write to system, formula, or lookup fields with +record-upsert.
  • Do not fall back to raw API calls (e.g., lark-cli api GET /open-apis/bitable/v1/...) for Base operations.
  • Always use the lark-cli base +... pattern.

When to Use lark-base

Use this skill when you need to:

  • Automate table or field creation and management within Lark Base.
  • Perform structured data imports, exports, or migrations.
  • Implement business logic with formula or lookup fields.
  • Generate analytics or reports that require cross-table calculations.
  • Manage user roles, forms, or dashboards programmatically.
  • Enforce strict data governance in collaborative environments.

This skill is essential for scenarios where field design, cross-table relationships, or complex data analysis are involved. It also helps transition legacy command patterns (e.g., +table, +field, +record) to the standardized base interface.

Important Notes

  • Field Types: Understand the three main field categories:
    • Storage fields: Accept user input and are writable.
    • System fields: Managed by the platform (e.g., created time, updated time) and are read-only.
    • Calculation fields: Derived from expressions or rules (formula and lookup fields) and are read-only.
  • Attachments: File fields require +record-upload-attachment.
  • Command Reference: Always consult the official documentation for each command prior to use.
  • Validation: Never rely on UI intuition or natural language for field or table names - always query structure programmatically.
  • Data Integrity: Avoid writing to non-storage fields to prevent errors or data corruption.

By adhering to these practices and leveraging the structured capabilities of lark-base, you can build robust, maintainable, and scalable automations within the Lark Base ecosystem.