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。首次启用前，需要完成两项一次性配置：

1. 在 npm 包 lark-project-cli 的 Settings → Trusted Publisher 配置 GitHub Actions：仓库填写 juzibot/lark-project-cli，工作流文件填写 publish.yml，允许操作选择 npm publish。
2. 在 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

推送 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