Lark Shared

Lark Shared Skill for Happycapy Skills Platform

What Is This?

The Lark Shared skill (lark-shared) is a productivity-focused extension for the Happycapy Skills platform, designed to streamline and secure access to Feishu/Lark resources via the lark-cli command-line tool. This skill provides foundational support for application configuration initialization, authentication and login operations, identity switching between user and bot modes, permission and scope management, error handling for permission issues, and security best practices.

By leveraging this skill, users and developers can ensure that their Lark CLI operations are correctly authorized, securely configured, and robust against common permission pitfalls. The skill is triggered when users first configure the Lark CLI (lark-cli config init), perform authentication login (lark-cli auth login), encounter insufficient permissions, switch between user and bot identities, or configure access scopes for the first time.

Why Use It?

Integrating with Feishu/Lark's API ecosystem requires careful handling of authentication, identity, and permissions. The Lark Shared skill addresses several key challenges:

• Secure Initialization: Ensures that the app is set up correctly before any sensitive operations occur.
• Role-Based Identity: Explicitly manages whether operations are performed as a user or as a bot, which fundamentally changes access and data visibility.
• Granular Permission Control: Handles missing permissions by guiding users to the correct configuration steps, supporting both developer (bot) and end-user (user) perspectives.
• Error Handling and Guidance: Surfaces actionable error messages, linking directly to Lark's developer console and providing repair commands.
• Best Practice Enforcement: Promotes least-privilege principles through precise scope authorization and discourages insecure practices.

This skill is essential for anyone building integrations or automations with Lark/Feishu, ensuring a smooth authorization flow and secure, compliant access to resources.

How to Use It

1. Configuration

Initialization

Before any Lark CLI operations, the application must be initialized. This is done with:

lark-cli config init --new

• This command triggers an interactive setup, which blocks until the user follows the generated authorization link and completes the process or the session expires.
• When automating setup for users, you can run this command in the background and extract the authorization URL from the output to guide users through the process.

2. Authentication and

Login

Lark CLI supports two identity types, controlled via the --as flag:

Example usage:

• As a user:
  bash

  lark-cli calendar list --as user
  # Prompts for user authentication if not already authorized

• As a bot:
  bash

  lark-cli calendar list --as bot
  # Only accesses the bot’s own resources

Note: The [identity: bot/user] output in command responses indicates the current identity context.

3. Switching

Identity

Use the --as flag to explicitly control the identity context. Always verify the identity context matches your intended resource target:

• Use --as user for personal resources (user calendar, user docs)
• Use --as bot for application resources or bot-owned content

4. Handling Insufficient

Permissions

When encountering permission errors, Lark CLI provides detailed error responses:

• permission_violations: Lists missing scopes required for the operation
• console_url: Direct link to the developer console’s permissions configuration page
• hint: Suggested command(s) to repair the permission issue

For Bot Identity (--as bot):

• Never run auth login as bot
• If a permission is missing, the resolution is to open the console_url in your browser and enable the required scope in the developer backend

For User Identity (--as user):

• The user must authorize the missing scopes via CLI:
  bash

  lark-cli auth login --domain <domain>           # Authorize for a business domain
  lark-cli auth login --scope "<missing_scope>"   # Authorize for specific scope (recommended)

  This ensures only the required permissions are granted, following the principle of least privilege.

5. Permission and Scope

Management

• All operations require that both the developer backend (for bots) and the user (for user identity) have enabled the relevant scopes.
• If permissions are insufficient, always follow the error message’s guidance to either adjust backend configuration (bot) or re-authenticate (user) with the precise scope.

When to Use It

Use the Lark Shared skill whenever you:

• Set up Lark CLI for the first time on any system
• Need to authenticate a new user or switch between user and bot accounts
• Encounter permission errors such as Permission denied, permission_violations, or missing scopes
• Require secure, auditable access to Lark resources for integrations, automations, or data extraction
• Are building applications or workflows that must dynamically switch identity context for different operations

This skill is especially valuable when onboarding new users, deploying to new environments, or integrating with third-party automations that require granular and secure access to Lark resources.

Important Notes

• Identity Separation: Bot and user identities are strictly separate. Bots cannot access user data such as calendars, docs, or email. Similarly, bot actions (such as sending messages or creating docs) are always attributed to the bot itself.
• Scope Principle: Always grant the minimum necessary scopes. Use lark-cli auth login --scope "<scope>" rather than broad domain authorizations.
• Error Handling: Pay close attention to error messages. They provide actionable information including which scopes are missing and how to resolve the issue.
• Security: Never attempt to use auth login for bots. Only user identities require explicit authorization.
• Automation: When scripting or automating, capture the authorization URL from lark-cli config init --new and ensure users complete the flow for secure operation.
• Compliance: Review and update permissions regularly in the developer backend to ensure ongoing compliance with organizational policies and Lark API changes.

The Lark Shared skill provides a robust, secure, and user-friendly foundation for working with Feishu/Lark resources, making it an essential tool for any developer or team integrating with the Lark ecosystem via CLI. For more details or advanced use cases, refer to the official GitHub repository.