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

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 | | MCP_USER_TOKEN | MCP user token (optional, for Claude integration) |

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>

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