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