How to Install Feishu CLI

System Requirements

Feishu CLI runs on all major operating systems and architectures. Before installing, make sure your system meets the following minimum requirements:

Node.js 16 or later — Required for the npm installation method and for the AI Agent skills system. Node.js 18+ is recommended for the best experience.
Operating System — macOS, Linux, and Windows are all fully supported. Both x64 and arm64 architectures are supported across all platforms, including Apple Silicon Macs and ARM-based Linux servers.
Go 1.23+ — Only required if you plan to build Feishu CLI from source. Pre-built binaries installed via npm do not require Go.

No additional system dependencies are needed. The CLI is distributed as a self-contained binary with all required libraries bundled.

Install via npm (Recommended)

The fastest way to get started with Feishu CLI is through npm. This installs the pre-built binary globally and sets up the AI Agent skills in a single step:

npm install -g @larksuite/cli
npx skills add larksuite/cli -y -g

The first command installs the lark-cli binary globally, making it available from any terminal session. The second command installs all 19 AI Agent skill files globally, which enables AI coding assistants like Claude Code and Cursor to understand and use Feishu CLI commands automatically.

After installation, you can verify that the binary is accessible by running lark-cli --version in your terminal. If you encounter permission errors on macOS or Linux, you may need to configure your npm prefix or use a Node version manager like nvm.

Install from Source

If you need the latest development version or want to contribute to the project, you can build Feishu CLI from source. This requires Go 1.23 or later to be installed on your system:

git clone https://github.com/larksuite/cli.git
cd cli
make install
npx skills add larksuite/cli -y -g

The make install command compiles the Go source code and places the resulting binary in your $GOPATH/bin directory. Make sure this directory is included in your system PATH. The skills installation step is the same regardless of whether you installed via npm or from source.

Building from source also gives you access to the full test suite and development tooling. Run make test to execute the test suite and make lint to check for code quality issues before submitting contributions.

Create a Lark App

Before you can use Feishu CLI, you need to create an application on the Lark Open Platform. This application provides the credentials that the CLI uses to authenticate API requests:

Visit open.larksuite.com/app (international) or open.feishu.cn/app (China) and log in with your Lark account.
Click "Create Custom App" and fill in the application name and description.
Navigate to the "Credentials & Basic Info" section to find your App ID and App Secret.
Keep these credentials secure — you will need them in the next configuration step.

The Lark app acts as the identity for your CLI sessions. All API calls made through the CLI are authorized under this application, so the permissions you grant to the app determine what the CLI can access.

Configure Credentials

Once you have your App ID and App Secret, use the interactive configuration command to store them securely:

lark-cli config init          # Interactive setup for humans
lark-cli config init --new    # For AI Agents, outputs auth URL

The standard config init command walks you through an interactive wizard that prompts for your App ID, App Secret, and preferred environment (Lark or Feishu). The --new flag is designed for AI agent workflows where interactive prompts are not possible — it outputs a direct authorization URL that can be opened programmatically.

Credentials are stored in a configuration file at ~/.lark-cli/config.yaml. The App Secret is encrypted at rest. You can manage multiple app configurations and switch between them as needed.

Authentication (OAuth 2.0 Device Flow)

After configuring your app credentials, you need to authenticate as a user to access user-scoped APIs. Feishu CLI uses the OAuth 2.0 Device Authorization Flow, which works in headless environments and SSH sessions:

lark-cli auth login --recommend     # Auto-select common scopes
lark-cli auth login --domain calendar,task  # Filter by domain
lark-cli auth login --no-wait       # Agent mode, non-blocking

The --recommend flag automatically selects the most commonly used permission scopes, which is ideal for getting started quickly. If you only need access to specific Lark domains, use the --domain flag to request a narrower set of permissions. The --no-wait flag is designed for AI agent workflows where the CLI should not block waiting for the user to complete the browser-based authorization.

After successful authentication, your OAuth tokens are stored in the OS-native keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service). This ensures tokens are encrypted at rest and protected by your operating system's security mechanisms. Tokens are automatically refreshed when they expire.

Verify Installation

After completing the installation and authentication steps, verify that everything is working correctly:

lark-cli auth status
lark-cli doctor

The auth status command shows your current authentication state, including the authenticated user, active scopes, and token expiration time. The doctor command runs a comprehensive health check that verifies your configuration file, authentication tokens, network connectivity to Lark APIs, and installed skill files.

If doctor reports any issues, it provides specific remediation steps for each problem. Common issues include expired tokens (resolved with lark-cli auth login), missing configuration (resolved with lark-cli config init), and network connectivity problems.

Shell Completion

Feishu CLI supports tab completion for all commands, subcommands, and flags in popular shells. To enable shell completion, run the appropriate command for your shell:

lark-cli completion bash    # Bash completion
lark-cli completion zsh     # Zsh completion
lark-cli completion fish    # Fish completion
lark-cli completion powershell  # PowerShell completion

Each command outputs a shell script that you can add to your shell configuration file (e.g., .bashrc, .zshrc). Once configured, you can press Tab to auto-complete command names, flag names, and in some cases, argument values like chat IDs and document titles.

Identity Switching

Feishu CLI supports operating as either a user or a bot. Many API endpoints behave differently depending on the identity context, so understanding this distinction is important:

lark-cli im send --chat "group-name" --text "Hello" --as user
lark-cli im send --chat "group-name" --text "Hello" --as bot

The --as user flag sends the message as the authenticated user, while --as bot sends it as the application bot. You can set a default identity with lark-cli config default-as user or lark-cli config default-as bot to avoid specifying it on every command.

User identity is required for operations that need user-specific context, such as accessing personal calendars or sending emails. Bot identity is useful for automated workflows and integrations where messages should come from the application rather than a specific person.

Troubleshooting

If you encounter problems during installation or usage, the built-in doctor command is your first line of defense:

lark-cli doctor

The doctor command performs a series of diagnostic checks covering configuration validity, authentication state, API connectivity, and skill file integrity. Each check reports a pass/fail status with detailed error messages and suggested fixes when problems are found.

Common issues and their solutions include:

Command not found — Ensure the npm global bin directory is in your PATH. Run npm bin -g to find the directory.
Authentication errors — Re-run lark-cli auth login --recommend to refresh your tokens.
Permission denied — Check that your Lark app has the required scopes enabled on the Open Platform console.
Network timeout — Verify your network can reach open.larksuite.com or open.feishu.cn. Configure a proxy if needed.