meegle-cli

Meegle CLI

English | 简体中文

Command-line tool for Meegle (Lark Project). Manage work items, schedules, and data from your terminal — no browser needed.

Install · Quick Start · Agent Skill · Commands · Enterprise Extensions · Auth · Config · Security · Contributing

Why Meegle CLI?

• Agent-Native — The setup wizard installs the bundled AI Agent Skill for Trae, Claude Code, Cursor, Windsurf, Gemini CLI and other agents. Every CLI command is designed for both humans and agents, with structured JSON output, --dry-run previews, and --device-code flows for non-TTY environments
• Broad Coverage — 16 business domains (work items, workflow, subtasks, comments, work hours, relations, my-work, views, charts, team, user, project, attachments, deliverables, resource library, WBS plan tables) and 50+ commands mapping to Meegle's core capabilities
• Two-Layer Parameters — Ergonomic --flag-name for everyday use, fallback --params for complex payloads like fields[] — pick the right granularity per call
• Flexible Output — json / table / ndjson / raw, with --select dot-path projection for piping to other tools
• Secure by Default — OS keychain credential storage, ${VAR} env-var templating so secrets never land in config files, multi-profile switching for staging / prod
• Enterprise-Extensible — Build a company distribution without forking this repository by importing the public cmd, Credential, Transport, and Platform packages at compile time

Features

Category	Capabilities
Work Items	Create, read, update, batch-read, query (MQL), list operation records, inspect metadata
Workflow	Transition nodes & states, update node fields, list available transitions and required fields
✅ Subtasks	Create, update, complete, rollback subtasks
Comments	Add and list comments on work items
⏱️ Work Hours	List work hour records, view team-member schedules
Relations	List related work items, inspect relation-type definitions
My Work	View this week / overdue / completed to-dos
️ Views	Create and update fixed views, search views by name
Charts	List charts under a view, fetch chart details
Team & User	List teams, team members, search users, view current login
️ Projects	Search projects by keyword
Attachments	Two-stage upload/download protocol — prepare-* basic commands plus +upload / +download end-to-end shortcuts
Deliverables	List deliverables with their root and source work items
Resource Library	Create resource templates, inspect resource library configuration
️ WBS Plan Tables	List draft / published plan rows, create / edit / publish / reset drafts, query draft progress, list element templates
Auth & Config	OAuth login, device-code flow, multi-profile config, env-var injection
URL Parsing	Offline decode of Meegle / Feishu Project URLs into url_kind + structured fields
Agent Skill	Pre-built skill for Trae / Claude Code / Cursor / Windsurf / Gemini CLI / Copilot

Installation

Requirements

• Node.js >= 16 (ships with npm / npx)

Run the setup wizard:

npx @lark-project/meegle@latest install

The wizard installs or upgrades the CLI globally, installs the AI Agent Skill, configures the Meegle host, and starts login.

Automatic update prompt

The npm-distributed CLI checks npm for a newer version at most once every 24 hours when it starts in an interactive terminal. When an update is available, it reads the released Added and Changed entries between the installed and latest versions from the CHANGELOG, then shows an interactive prompt:

✨ Meegle CLI update available: v → v

What's new:
  v
    • Added: 

❯ Update now (recommended)
  Remind me later
  Use ↑/↓ to select, then press Enter

Pressing Enter first upgrades the CLI with npm install -g @lark-project/meegle@latest, then makes a best-effort attempt to upgrade the Meegle Agent Skill through the same installer used by meegle install, and finally continues the original command. A missing or incompatible Skill installer, or a Skill download failure, never changes a successful CLI upgrade into a failure. Choosing Remind me later defers the next check for 24 hours. This lightweight update does not reconfigure the host or trigger login; use meegle install when you want the full setup wizard.

The check is skipped for non-interactive/CI execution, piped stdout, install, and shell-completion commands, so structured command output remains unchanged. Set MEEGLE_NO_UPDATE_CHECK=1 to disable it explicitly.

Quick Start (Human Users)

Note for AI assistants: if you are an AI Agent helping the user set this up, jump directly to Quick Start (AI Agent) — it contains the non-interactive command you need.

# 1. Install CLI + Skill, configure host, and log in
npx @lark-project/meegle@latest install

# 2. View this week's to-dos
meegle mywork todo --action this_week --page-num 1

# 3. View help
meegle --help
meegle workitem --help

# 4. Inspect command parameters
meegle inspect workitem.create

Quick Start (AI Agent / CI / Headless)

The default browser OAuth flow requires a real TTY. In CI runners, pipes, and agent shells like Claude Code, run the same setup wizard with an explicit host and Device Code login:

npx -y @lark-project/meegle@latest install --host  --device-code --lang en

Examples of ``: project.feishu.cn, meegle.com, or your self-hosted tenant domain such as your-tenant.example.com. The Device Code flow prints an authorization URL; send it to the user and keep the command running until authorization completes.

Verify:

meegle auth status

For fully unattended CI (no human-in-the-loop), inject a token via environment variables instead — see Sandbox / CI.

AI Agent Skill

The setup wizard installs skills/meegle/, a drop-in skill for Trae, Claude Code, Cursor, Windsurf, Gemini CLI, GitHub Copilot CLI, and other agents. It teaches agents how to operate Meegle through this CLI instead of guessing command shapes from prose.

What it covers

• Command reference — every meegle resource / method with required parameters and examples
• MQL search — syntax for workitem query, operators, scope keywords
• Field values — how to shape complex field payloads (arrays, nested JSON, date ranges)
• Rich text — Markdown subset supported by Meegle's rich-text editor
• SOPs — step-by-step playbooks for creating work items, transitioning nodes, transitioning states, and updating fields
• Auth guard — the skill refuses to run business commands until meegle auth status succeeds

Usage

Once the setup wizard has run, ask the agent in natural language. For example:

Show me this week's P0 stories in the PROJ space.

The agent consults the skill, picks the right meegle commands, and runs them for you. Pair with --dry-run (see Security) to preview side-effectful operations before the agent commits them.

Commands

workitem — Work Items

Command	Description
workitem create	Create a work item
workitem get	View work item details
workitem +batch-get	Batch-read work items by IDs (client-side fan-out over workitem get; + marks scenario/sugar commands)
workitem update	Update work item fields
workitem query	Search work items using MQL
workitem list-op-records	View operation records
workitem meta-types	List work item types
workitem meta-create-fields	List fields available at creation
workitem meta-fields	List field configurations
workitem meta-roles	List role configurations

workflow — Workflow

Command	Description
workflow transition	Transition or rollback a node
workflow transition-state	Transition a state-flow state
workflow get-node	View node details
workflow update-node	Update a node
workflow meta-node-fields	List node field configurations
workflow list-state-transitions	List available state transitions
workflow list-state-required	List required fields for transitions

subtask — Subtasks

Command	Description
subtask update	Create / update / complete / rollback subtasks

comment — Comments

Command	Description
comment add	Add a comment
comment list	List comments

workhour — Work Hours

Command	Description
workhour list-records	List work hour records
workhour list-schedule	View team member schedules

relation — Relations

Command	Description
relation list	List related work items
relation meta-definitions	List relation type definitions

mywork — My Work

Command	Description
mywork todo	View my to-dos / completed items

view — Views

Command	Description
view create-fixed	Create a fixed view
view get	View details of a view
view update-fixed	Update a fixed view
view search	Search views by name
view list-multi-project-workitems	List work items under a multi-project (panoramic) view

chart — Charts

Command	Description
chart get	View chart details
chart list	List charts under a view

team / user — People

Command	Description
team list	List teams in a project
team list-members	List team members
user me	View current logged-in user information
user search	Search user information

project — Projects

| Command | Description