lark-project-cli

Lark Project CLI — A command-line tool for managing work items in Lark Project spaces, supporting queries, search, filtering, file uploads, and more.

Why CLI instead of the web UI?

Scenario	Web UI	CLI
Batch view work items	Manual pagination, click one by one	`list-items --type bug --all` one-click export
Cross-type relation query	Jump between multiple pages	`list-related <ID>` direct view
Data export & analysis	Manual copy or Excel export	`--format csv` pipe to other tools
Automation / CI integration	Not supported	All commands support scripting
AI tool integration	Not supported	MCP protocol support, works with Claude and other AI tools

Typical use cases:

Product managers: Quickly view sprint progress, backlog status, user story workflows
Developers: View task lists, related bugs, work item details
QA engineers: Batch view bugs, search by priority, view status distribution
Ops / DevOps: View online update records, ticket lists, release versions

Installation

Option 1: npx (recommended)

npx lark-project-cli setup
npx lark-project-cli list-types

Option 2: Global install

npm install -g lark-project-cli
lark-project setup

Option 3: Build from source

git clone <repo-url> && cd lark-project-cli
npm install
npm run build
npm link   # optional: link as global command

升级

main 合并后的版本需要先发布到 npm，其他用户再按自己的安装方式升级。升级不改动已有的插件凭据：全局配置仍在 ~/.lark-project/config，项目级配置仍在当前目录的 .env。

通过 npx 使用

每次使用时指定 @latest，即可拉取 npm 上最新已发布版本：

npx --yes lark-project-cli@latest list-types

全局安装用户

npm install -g lark-project-cli@latest
lark-project --version
lark-project doctor

若要使用 MCP，升级后重启 MCP 客户端（例如 Claude Desktop、Cursor 或 Codex）；配置中的命令保持为 lark-project-mcp 即可。

{
  "command": "lark-project-mcp"
}

源码安装用户

在已有仓库中同步 main 并重新安装、构建：

cd /path/to/lark-project-cli
git fetch origin
git switch main
git pull --ff-only origin main
npm ci
npm run build
npm link
lark-project --version

如果 MCP 配置的 command 是 node 且 args 指向仓库内的 dist/mcp/cli.js，构建完成后重启 MCP 客户端即可加载新版本。

维护者发版

发布由 GitHub Actions 完成，不能在本机直接执行 npm publish。首次启用前，需要完成两项一次性配置：

在 npm 包 lark-project-cli 的 Settings → Trusted Publisher 配置 GitHub Actions：仓库填写 juzibot/lark-project-cli，工作流文件填写 publish.yml，允许操作选择 npm publish。
在 GitHub 仓库 Settings → Environments 创建 npm-production，并设置发布审批人。发布工作流会等待该环境审批。

之后每个版本按以下步骤发布：

# 1. 在功能分支更新 package.json 与 package-lock.json 中的版本，走 PR 合并 main。

# 2. main 合并后，在 main 的对应提交创建并推送同名标签。
git checkout main
git pull --ff-only origin main
git tag -a v1.0.3 -m "release: v1.0.3"
git push origin v1.0.3

通过 GitHub CLI 创建发布 PR 时，正文必须使用 Markdown 文件传入，避免把换行转义字符显示成普通文本：

gh pr create --base main --head release/2026-08-14 \
  --title "release: prepare v1.0.3" \
  --body-file /tmp/lark-project-cli-pr.md

仓库的 PR 模板提供了统一的“变更、验证、风险与回滚”结构。不要在 --body 参数中拼接转义换行来创建多行正文。

推送 v* 标签后，发布工作流会校验标签和 package.json 版本一致、标签提交已在 main，然后安装依赖、构建、打包预演并发布到 npm。发布过程使用 npm Trusted Publishing 的短期 OIDC 身份，不保存 npm Token、OTP 或通行密钥。PR 和 main 推送会由 CI 工作流执行构建和打包预演。

Configuration

Admin first-time setup

lark-project setup

The wizard guides you through creating a plugin, verifying credentials, and selecting user identity. After completion, it shows the information needed for team members to join.

Team member quick join

After admin completes setup, share Plugin ID / Secret / Project Key with members, who then run:

lark-project setup --join

Just enter the credentials provided by admin, then select yourself from the team list.

CI/CD non-interactive mode

export LARK_PROJECT_KEY=my-project
export LARK_PLUGIN_ID=MII_xxx
export LARK_PLUGIN_SECRET=xxx
export LARK_USER_KEY=xxx
lark-project setup --env

Config file locations

Config is loaded with this priority: Environment variables > Project .env > Global config

Location	Path	Description
Global config	`~/.lark-project/config`	Written by `setup` wizard, shared across all directories
Project override	`.env` in current directory	Optional, overrides global config
Environment variables	-	Highest priority, ideal for CI/CD

Manual configuration

See Setup Guide for detailed credential acquisition steps.

Environment Variable	Description
`LARK_BASE_URL`	Lark Project URL, default `https://project.feishu.cn`
`LARK_PROJECT_KEY`	Project space key
`LARK_PLUGIN_ID`	Plugin ID
`LARK_PLUGIN_SECRET`	Plugin Secret
`LARK_USER_KEY`	User key

Diagnostics

lark-project doctor

Automatically checks config files, credential validity, network connectivity, and API access permissions, with fix suggestions.

Usage

# Development mode
npm run dev -- <command> [options]

# After build
lark-project <command> [options]

Global options

Option	Description	Default
`--project-key <key>`	Override project space key from .env	Value from `.env`
`--format <type>`	Output format: `json` / `table` / `csv`	`json`
`--verbose`	Verbose output (includes API request logs)	`false`

Commands

`setup` — Interactive setup wizard

lark-project setup [options]

Option	Description
`--join`	Member quick join mode (admin has provided credentials)
`--env`	Generate .env from environment variables (CI/CD non-interactive mode)
`--force`	Skip overwrite confirmation for existing config
`--skip-verify`	Skip credential verification

`doctor` — Diagnose config and connectivity

lark-project doctor

Checks config files, credential validity, network connectivity, API access permissions, with fix suggestions.

`list-types` — List work item types

lark-project list-types

`list-teams` — List team members

lark-project list-teams

`list-items` — List work items

lark-project list-items --type <type> [options]

Option	Description
`--type <type>`	Required Work item type, supports api_name or Chinese alias
`--tags <tags>`	Filter by tags, comma-separated
`--status <status>`	Filter by status (state_key)
`--name <name>`	Fuzzy search by name
`--page <n>`	Page number, default `1`
`--size <n>`	Page size, default `50`
`--all`	Auto-paginate to get all data

Examples:

# List all user stories
lark-project list-items --type story --all

# Filter bugs by status
lark-project list-items --type bug --status resolved

# Table format output
lark-project list-items --type sub_task --format table

`get-item <id>` — Get work item details

lark-project get-item <id> --type <type> [--expand <fields>]

--expand supports: workflow (default), multi_text, relations, comma-separated.

`get-workflow <id>` — View workflow status and schedule

lark-project get-workflow <id> --type <type>

Returns workflow node status (not started/in progress/completed), assignees, schedule, and actual completion time.

`search` — Search work items by field

lark-project search --type <type> --field <field_key> --value <value> [--operator <op>]

--operator supports: = (default), !=, >, <, contains.

`list-related <id>` — Get related work items

lark-project list-related <id> --type <type>

View work item relations (e.g., contract→payment, bug→story).

`list-states` — List status distribution

lark-project list-states --type <type> [--sample-size <n>]

Discovers all possible statuses and their distribution by sampling, default 500 items.

`upload-file` — Upload file to work item

lark-project upload-file --type <type> --id <id> --field <field_key> --url <file_url>

--field-alias 可用于附件字段在当前空间要求别名的场景。

MCP Server

仓内 MCP Server 复用 CLI 的插件凭据，不再依赖远程 @lark-project/mcp 代理。构建后运行：

npm run build
npm run mcp

将 mcp.example.json 配置加入 MCP 客户端，并通过环境变量注入 LARK_PROJECT_KEY、LARK_PLUGIN_ID、LARK_PLUGIN_SECRET 与 LARK_USER_KEY；不要在配置文件中写入真实密钥。

读工具：list_work_item_types、list_team_members、get_work_item、list_work_items、search_work_items、get_comments、get_workflow、list_related_work_items。

写工具：create_work_item、update_work_item、transition_work_item、add_comment、update_comment、upload_attachment、unlink_space_relation。每个写工具默认为 mode=preview，返回五分钟有效、一次性的 operationToken；提交时传入相同参数和 mode=commit。

transition_work_item 需要飞书项目返回的 transitionId，不接受展示状态名。当前不提供“绑定关联工作项”工具：跨空间绑定请求体尚未从公开 API 契约确认，避免因猜测参数误写数据。

Supported work item types

Type parameter supports api_name and Chinese aliases:

Alias	api_name	Description
用户故事 / 故事	`story`	User Story
缺陷 / bug	`issue`	Bug
工单	`workorder`	Ticket
迭代	`sprint`	Sprint
史诗	`system_epic`	Epic
特性	`characteristic_`	Feature
发布版本 / 版本	`version`	Release Version
线上更新 / 线上系统更新	`update`	Online Update
任务	`sub_task`	Task
需求池	`backlog`	Backlog
测试计划	`test_plans`	Test Plan
用例管理	`test_cases_set`	Test Cases
客户	`client`	Client
合同	`contract`	Contract
回款	`refund`	Payment

Project Structure

src/
├── cli.ts                  # Entry point, registers all commands
├── config.ts               # Env vars, type mapping, alias resolution
├── formatter.ts            # Output formatting (json/table/csv)
├── types.ts                # TypeScript type definitions
├── commands/
│   ├── setup.ts            # Interactive setup wizard
│   ├── doctor.ts           # Config & connectivity diagnostics
│   ├── list-types.ts       # List work item types
│   ├── list-teams.ts       # List team members
│   ├── list-items.ts       # List work items (filter/paginate)
│   ├── list-states.ts      # List status distribution
│   ├── list-related.ts     # Get related work items
│   ├── get-item.ts         # Get work item details
│   ├── get-workflow.ts     # View workflow status
│   ├── search.ts           # Search by field
│   └── upload-file.ts      # Upload files
├── services/
│   └── api-client.ts       # Lark API client (auth, requests, pagination, cache)
└── utils/
    ├── batch.ts            # Batch processing utilities
    ├── cache.ts            # Token/data cache
    ├── config-path.ts      # Config file path management (global/project)
    ├── prompt.ts           # Interactive input utilities
    └── quarter.ts          # Quarter time utilities

Development

# Dev mode
npm run dev -- list-types --verbose

# Build
npm run build

# Run built output
npm start -- list-items --type story --all --format table

License

ISC

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
src		src
test		test
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
mcp.example.json		mcp.example.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

lark-project-cli

Why CLI instead of the web UI?

Installation

Option 1: npx (recommended)

Option 2: Global install

Option 3: Build from source

升级

通过 npx 使用

全局安装用户

源码安装用户

维护者发版

Configuration

Admin first-time setup

Team member quick join

CI/CD non-interactive mode

Config file locations

Manual configuration

Diagnostics

Usage

Global options

Commands

setup — Interactive setup wizard

doctor — Diagnose config and connectivity

list-types — List work item types

list-teams — List team members

list-items — List work items

get-item <id> — Get work item details

get-workflow <id> — View workflow status and schedule

search — Search work items by field

list-related <id> — Get related work items

list-states — List status distribution

upload-file — Upload file to work item

MCP Server

Supported work item types

Project Structure

Development

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages