sheets (v3)

sheets (v3) Skill for Happycapy:

Technical Overview

What Is This

The sheets (v3) skill (lark-sheets) for the Happycapy Skills platform is a command-line tool designed to automate the creation and manipulation of Feishu (Lark Suite) spreadsheets. It allows users to programmatically create spreadsheets, write headers and data, read and write cell values, append rows, search for cell contents within known spreadsheets, and export spreadsheet files. This skill enables streamlined data operations on Feishu Sheets without manual interaction, making it suitable for batch processing and integration with other automation workflows.

The skill is implemented as a CLI extension and requires the lark-cli binary. Its source code and usage documentation can be found at: https://github.com/larksuite/cli/tree/main/skills/lark-sheets.

Why Use It

The sheets (v3) skill is particularly useful for teams and individuals who need to manage large volumes of spreadsheet data within the Feishu ecosystem efficiently. Common scenarios include:

• Programmatically generating new spreadsheets for reporting or logging purposes.
• Reading and writing large datasets to Feishu Sheets as part of automated workflows.
• Searching for specific data points within existing sheets.
• Exporting spreadsheets for backup, sharing, or downstream processing.

Manual spreadsheet operations are time-consuming and error-prone when performed at scale. By leveraging this skill, users can minimize human error, improve efficiency, and build robust, repeatable data management processes.

How to Use It

Prerequisites

• Ensure lark-cli is installed and properly configured with authentication and permissions for your Feishu account.
• Obtain the correct file_token for the spreadsheet you want to manipulate. See the section on "Document Types and Token Handling" below.

Basic Command Structure

The skill exposes several subcommands via lark-cli sheets, including creation, reading, writing, finding, and exporting. Use lark-cli sheets --help to view all available options.

1. Creating a New

Spreadsheet

To create a new spreadsheet and write headers and data:

lark-cli sheets +create \
  --title "Monthly Report" \
  --headers "Date,Revenue,Expenses" \
  --data "2024-06-01,1000,500;2024-06-02,1100,600"

2. Reading Cell

Values

To read the value of a specific cell:

lark-cli sheets +read \
  --file-token shtcnxxxxxxxxx \
  --sheet-name "Sheet1" \
  --cell "B2"

3. Writing Cell

Values

To write a value into a specific cell:

lark-cli sheets +write \
  --file-token shtcnxxxxxxxxx \
  --sheet-name "Sheet1" \
  --cell "C3" \
  --value "Approved"

4. Appending

Rows

To append new rows to an existing sheet:

lark-cli sheets +append \
  --file-token shtcnxxxxxxxxx \
  --sheet-name "Sheet1" \
  --data "2024-06-03,1200,700"

5. Searching for Cell

Content

To find a cell containing specific content:

lark-cli sheets +find \
  --file-token shtcnxxxxxxxxx \
  --sheet-name "Sheet1" \
  --query "Revenue"

6. Exporting a

Spreadsheet

To export a spreadsheet file for download or backup:

lark-cli sheets +export \
  --file-token shtcnxxxxxxxxx \
  --format xlsx \
  --output "./downloads/monthly_report.xlsx"

Document Types and Token Handling

Feishu documents come in several types, each with unique URL and token formats. For spreadsheets (/sheets/), the token embedded in the URL path (e.g., shtcnxxxxxxxxx in https://example.larksuite.com/sheets/shtcnxxxxxxxxx) is used as the file_token in all operations.

For other document types (such as /docx/, /wiki/), token handling may differ. Always ensure you are using the correct token type for your operation. For sheet operations, only use tokens from /sheets/ URLs.

Searching for Spreadsheets

If you do not have the file token or sheet URL, use the lark-cli docs +search command with a title or keyword to locate the file. Note that docs +search returns results of type SHEET along with other document types.

When to Use It

Use the sheets (v3) skill when you need to:

• Automate the creation of Feishu spreadsheets for reporting, data collection, or analysis.
• Perform batch reading and writing of spreadsheet data as part of a larger workflow.
• Locate and extract or update specific data points within known spreadsheets.
• Export spreadsheet files for archiving or sharing.
• Minimize manual spreadsheet work and improve data integrity in Feishu.

Do not use this skill if you only need to search for spreadsheet files by name or keyword-use lark-cli docs +search for that purpose, then proceed with sheets subcommands once you have the file token.

Important Notes

• Authentication and Permissions: Before using this skill, review the authentication and permission requirements detailed in the shared documentation (lark-shared/SKILL.md). Insufficient permissions will cause operations to fail.
• Token Accuracy: Always use the correct token type for the document. For spreadsheet operations, use the file_token from the /sheets/ URL. Do not use tokens from /wiki/ or other document types.
• Batch Operations: The skill is designed for robust batch operations, but always validate data integrity after large updates.
• Export Format: When exporting spreadsheets, specify the desired format (e.g., xlsx) and ensure the output path is writable.
• Command Help: Use lark-cli sheets --help for an up-to-date list of options and subcommands.

By following these guidelines and leveraging the sheets (v3) skill, you can significantly streamline your Feishu spreadsheet workflows and integrate them seamlessly with your automation infrastructure.