@tingwillforever/meegle-cli 1.0.0-dev.20260519131637322

package/README.md

@@ -0,0 +1,777 @@
+# Meegle CLI
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D16-brightgreen.svg)](https://nodejs.org/)
+[English](./README.md) | [简体中文](./README.zh-CN.md)
+
+Command-line tool for [Meegle](https://meegle.com?utm_source=github&utm_medium=readme&utm_campaign=meegle_cli) ([Lark Project](https://project.feishu.cn?utm_source=github&utm_medium=readme&utm_campaign=meegle_cli)). Manage work items, schedules, and data from your terminal — no browser needed.
+
+[Install](#installation) · [Quick Start](#quick-start) · [Agent Skill](#ai-agent-skill) · [Commands](#commands) · [Auth](#authentication) · [Config](#configuration) · [Security](#security--risk-warnings) · [Contributing](#contributing)
+
+## Why Meegle CLI?
+
+- **Agent-Native** — Ships a bundled [AI Agent Skill](#ai-agent-skill) that teaches Trae, Claude Code, Cursor, Windsurf, Gemini CLI and other agents how to drive Meegle with one command. Every CLI command is designed for both humans and agents, with structured JSON output and `--dry-run` previews
+- **Broad Coverage** — 12 business domains (work items, workflow, subtasks, comments, work hours, relations, my-work, views, charts, team, user, project) and 40+ commands mapping to Meegle's core capabilities
+- **Two-Layer Parameters** — Ergonomic `--flag-name` for everyday use, fallback `--params <json>` 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
+
+## Features
+
+| Category                                           | Capabilities                                                                                   |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| 📋 [Work Items](#workitem--work-items)             | Create, read, update, batch-read, query (MQL), list operation records, inspect metadata        |
+| 🔀 [Workflow](#workflow--workflow)                 | Transition nodes & states, update node fields, list available transitions and required fields |
+| ✅ [Subtasks](#subtask--subtasks)                  | Create, update, complete, rollback subtasks                                                    |
+| 💬 [Comments](#comment--comments)                  | Add and list comments on work items                                                            |
+| ⏱️ [Work Hours](#workhour--work-hours)             | List work hour records, view team-member schedules                                             |
+| 🔗 [Relations](#relation--relations)               | List related work items, inspect relation-type definitions                                     |
+| 📌 [My Work](#mywork--my-work)                     | View this week / overdue / completed to-dos                                                    |
+| 👁️ [Views](#view--views)                           | Create and update fixed views, search views by name                                            |
+| 📊 [Charts](#chart--charts)                        | List charts under a view, fetch chart details                                                  |
+| 👥 [Team & User](#team--user--people)              | List teams, team members, search users, view current login                                     |
+| 🗂️ [Projects](#project--projects)                  | Search projects by keyword                                                                     |
+| 🔐 [Auth & Config](#authentication)                | Remote MCP SSO config, profile config, env-var injection                                       |
+| 🤖 [Agent Skill](#ai-agent-skill)                  | Pre-built skill for Trae / Claude Code / Cursor / Windsurf / Gemini CLI / Copilot              |
+
+## Installation
+
+### Requirements
+
+- Node.js >= 16 (ships with `npm` / `npx`)
+
+### Install
+
+Install the published package with a GitHub token that can read packages:
+
+```bash
+npm config set @tingwillforever:registry https://npm.pkg.github.com
+npm config set //npm.pkg.github.com/:_authToken <github_pat_with_read_packages>
+npm install -g @tingwillforever/meegle-cli@latest
+```
+
+## Quick Start
+
+For ordinary users, the CLI is a thin client for the deployed Meegle MCP Server.
+You do not need to configure plugin credentials, project credentials, or a local
+MCP runtime.
+
+```bash
+# 1. Start ordinary-user remote MCP SSO login
+meegle auth login
+
+# 2. Inspect the current authorization summary returned by the server
+meegle auth whoami --format table
+
+# 3. Verify the installed CLI and runtime
+meegle version
+meegle doctor --format json
+```
+
+`auth login` opens the browser, completes enterprise SSO, exchanges the SSO
+ticket for an MCP-managed session, and stores the refreshable session locally.
+The production package should embed the production MCP endpoint. Use
+`mcp_server_url` or `--mcp-server-url ...` only for local debugging, staging, or
+temporary bootstrap.
+
+`auth whoami` shows the authenticated domain account plus the Meegle user key,
+project scope, and business-line scope returned by the server.
+
+If login reports that access must be requested or approved, SSO has identified
+you successfully but the MCP Server has not found an active access grant for
+your account yet. Ask an administrator to approve or maintain your grant through
+the MCP Server access-request / access-grant APIs.
+
+If `doctor` fails, stop and fix runtime/config first. Do not start with business commands.
+
+## AI Agent Skill
+
+`skills/meegle/` is a drop-in **skill** that teaches AI Agents — Trae, Claude Code, Cursor, Windsurf, Gemini CLI, GitHub Copilot CLI — how to operate this repository's **private Meegle deployment** through the installed `meegle` CLI. It is aligned to the validated private runtime: both ordinary users and administrators authenticate through the remote MCP Server with SSO-backed sessions.
+
+### Install
+
+Complete [Installation](#installation) first, then install the skill:
+
+```bash
+npx -y skills add tingwillforever/meegle-cli --skill meegle -y -g
+```
+
+Private-repository install prerequisites:
+
+- the machine must already be able to access `tingwillforever/meegle-cli`
+- `skills add` will clone the private GitHub repository, so the user should authenticate with GitHub first, for example with `gh auth login`, or have working git/SSH credentials for that repository
+
+### What it covers
+
+- **Private runtime guidance** — remote MCP SSO setup and validation
+- **Verified command surface** — default-safe vs conditional command choices
+- **Current command recipes** — examples aligned to the installed CLI schema
+- **Field values** — how to shape write payloads safely for the private workflow
+- **SOPs** — compact write-flow playbooks for create, update, and workflow operations
+- **Installed-package E2E** — the maintained regression path for ordinary users
+
+See [skills/meegle/SKILL.md](./skills/meegle/SKILL.md) and [skills/meegle/references/](./skills/meegle/references/) for the full contents.
+
+This skill is intentionally scoped to the private installed-CLI maintenance workflow. It does not redefine the ordinary-user login contract, which now defaults to remote MCP SSO via `meegle auth login`.
+
+### Usage
+
+Once installed, just ask the agent in natural language. For example, in Trae:
+
+```
+Show me this week's P0 stories in the PROJ space.
+```
+
+The agent consults the skill, runs `meegle doctor` first when needed, picks the right private-deployment commands, and runs them for you. Pair with `--dry-run` (see [Security](#security--risk-warnings)) to preview side-effectful operations before the agent commits them.
+
+> Heads up: the skill name `meegle` is the same string as the CLI binary. When documentation refers to "the **`meegle` skill**" it means the files in `skills/meegle/`; when it refers to "the **`meegle` CLI**" it means the `meegle` command on your PATH.
+
+## 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 search-by-params` | Search work items with structured field filters |
+| `workitem search-filter` | Search work items by title/name filter |
+| `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 update-node` | Update a node |
+| `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 |
+|---------|-------------|
+
+### 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 |
+
+### chart — Charts
+
+| Command | Description |
+|---------|-------------|
+| `chart get` | View chart details |
+| `chart list` | List charts under a view |
+
+### team / user — People
+
+| Command | Description |
+|---------|-------------|
+| `team list-members` | List team members |
+| `user me` | View current logged-in user information |
+| `user query` | Query user information |
+
+### space — Projects
+
+| Command | Description |
+|---------|-------------|
+| `space list` | List projects |
+
+### auth — Authentication
+
+| Command | Description |
+|---------|-------------|
+| `auth login` | Start remote MCP SSO login |
+| `auth logout` | Log out and revoke the remote session when possible |
+| `auth status` | View login status |
+| `auth whoami` | Show the current authenticated identity and authorization summary |
+
+### config — Configuration
+
+| Command | Description |
+|---------|-------------|
+| `config init` | Initialize configuration |
+| `config show` | Show current configuration |
+| `config set` | Set a configuration value |
+| `config get` | Get a configuration value |
+| `config profile create\|list\|use\|current\|delete` | Manage configuration profiles |
+
+### Other Commands
+
+| Command | Description |
+|---------|-------------|
+| `inspect [command]` | Inspect command parameters |
+| `completion bash\|zsh\|fish` | Generate shell completion script |
+| `completion install` | Auto-install shell completion |
+
+## Deploy Tasks
+
+Deploy-task support follows a release-first command surface so both humans and AI agents can stay on the higher-level workflow before dropping to Kubelink atomic tools.
+
+Preferred flow:
+
+1. `meegle doctor --format json`
+2. `meegle release deploy-task-list --project-key PROJ --release-id RELEASE_ID --format json`
+3. `meegle release deploy-task-inspect --project-key PROJ --release-id RELEASE_ID --recordID RECORD_ID --format json` when a specific task or pod status matters
+4. `meegle release deploy-task-prepare ... --format json`
+5. only then `release deploy-task-create`, `release deploy-task-execute`, or `release deploy-task-verify`
+6. if execute returns whitelist guidance, confirm with the user and run `release deploy-task-apply-white-list`, then retry execute after approval
+
+Production release-plan gating:
+
+- before `release deploy-task-create`, the target `RELEASE_ID` must be the release plan explicitly confirmed for the current deployment request
+- old conversation context, a stale `RELEASE_ID`, or any merely in-progress release plan MUST NOT be auto-reused for a new deployment request
+- if the user has not yet confirmed which release plan this deployment should follow, stop and ask them to confirm an existing release plan or create a new one
+- if the release plan is already completed, the CLI must reject `deploy-task-create`
+- read-path commands such as `release deploy-task-list`, `release deploy-task-inspect`, and `release deploy-task-prepare` remain the default next steps when release-plan context is missing or no longer eligible
+
+Verification-state guidance:
+
+- `release deploy-task-prepare`
+- `release deploy-task-list`
+- `release deploy-task-inspect`
+- `integration kubelink-app-catalog-resolve`
+
+These are `verified` and are the default-safe first picks.
+
+- `release deploy-task-create`
+- `release deploy-task-execute`
+- `release deploy-task-apply-white-list`
+- `release deploy-task-verify`
+- `integration kubelink-deploy-task-create`
+- `integration kubelink-deploy-task-upgrade`
+- `integration kubelink-deploy-task-verify`
+- `integration kubelink-deploy-task-apply-white-list`
+- `integration kubelink-deploy-task-inspect`
+
+These are `conditional`. Use `meegle inspect <resource>.<method>` first if the parameter shape is unclear, and do not run them blindly in agentic workflows.
+
+Advanced fallback:
+
+- stay on `release` commands for ordinary release-oriented deploy-task requests
+- use `integration` only when you already have exact Kubelink payloads or record IDs, or when the release-layer command cannot express the action
+
+## Common Examples
+
+### Querying Work Items
+
+```bash
+# View work item details
+meegle workitem get \
+  --project-key PROJ \
+  --work-item-type-key WORK_ITEM_TYPE_KEY \
+  --work-item-ids 12345
+
+# View workflow state, nodes, and transitions
+meegle workflow list-state-transitions \
+  --project-key PROJ \
+  --work-item-type-key WORK_ITEM_TYPE_KEY \
+  --work-item-id 12345
+```
+
+### Batch Reading Work Items
+
+`workitem +batch-get` fans out to `workitem get` for each ID and aggregates the
+results into one response. Shared flags (e.g. `--project-key`) apply to every
+per-item call. The `+` prefix marks it as a scenario/sugar command with no 1:1
+MCP tool behind it — the CLI composes multiple `get` calls client-side.
+
+```bash
+# Comma-separated IDs in one invocation
+meegle workitem +batch-get --project-key PROJ --work-item-ids "12345,12346,12347"
+
+# Read IDs from a file (one per line; lines starting with '#' are comments)
+meegle workitem +batch-get --project-key PROJ --ids-file ./ids.txt
+
+# Stream one JSON row per item; summary row is emitted last
+meegle workitem +batch-get --project-key PROJ --work-item-ids "12345,12346" -o ndjson
+```
+
+Response envelope (JSON):
+
+```json
+{
+  "summary": { "total": 3, "succeeded": 2, "failed": 1 },
+  "results": [
+    { "work_item_id": 12345, "data": { /* ... */ } },
+    { "work_item_id": 12346, "data": { /* ... */ } },
+    { "work_item_id": 12347, "error": { "code": "...", "message": "..." } }
+  ]
+}
+```
+
+Constraints: up to 200 IDs per invocation, 3 concurrent workers (fixed).
+Partial failures do **not** abort the batch — check `summary.failed` or the
+per-item `error` field. A 401 from the server aborts the whole run.
+
+### Creating Work Items
+
+```bash
+# Pass fields[] via --params (JSON)
+meegle workitem create --project-key PROJ --work-item-type story \
+  --params '{"fields":[
+    {"field_key":"name","field_value":"Optimize login flow"},
+    {"field_key":"priority","field_value":"P1"}
+  ]}'
+
+# Complex field values (arrays, nested JSON) also go through --params
+meegle workitem create --project-key PROJ --work-item-type story \
+  --params '{"fields":[
+    {"field_key":"name","field_value":"Scheduled task"},
+    {"field_key":"schedule","field_value":[1722182400000,1722355199999]}
+  ]}'
+```
+
+### Updating Fields
+
+```bash
+# Update work item name
+meegle workitem update --work-item-id 12345 \
+  --params '{"fields":[{"field_key":"name","field_value":"New title"}]}'
+
+# Update multiple fields at once
+meegle workitem update --work-item-id 12345 \
+  --params '{"fields":[
+    {"field_key":"name","field_value":"New title"},
+    {"field_key":"priority","field_value":"P0"}
+  ]}'
+```
+
+### Work Item Search
+
+```bash
+# Query P0 stories in a project by title/name filter
+meegle workitem search-filter --project-key PROJ \
+  --work-item-type-key STORY_TYPE_KEY \
+  --name P0
+```
+
+### Viewing Schedules
+
+```bash
+# View team member schedules
+meegle workhour list-schedule --project-key PROJ \
+  --start-time 2026-03-01 --end-time 2026-03-31 \
+  --user-keys "Alice,Bob,Charlie"
+```
+
+### Searching Users
+
+```bash
+meegle user query --user-keys "Alice,Bob"
+```
+
+### Deploy Tasks
+
+```bash
+# Prepare a release-oriented deploy-task payload
+meegle release deploy-task-prepare \
+  --project-key PROJ \
+  --release-id RELEASE_ID \
+  --appName APP_NAME \
+  --format json
+
+# List deploy tasks bound to a release
+meegle release deploy-task-list \
+  --project-key PROJ \
+  --release-id RELEASE_ID \
+  --format json
+
+# Inspect one deploy task with release context
+meegle release deploy-task-inspect \
+  --project-key PROJ \
+  --release-id RELEASE_ID \
+  --recordID RECORD_ID \
+  --format json
+
+# Apply whitelist from the release layer after explicit user confirmation
+meegle release deploy-task-apply-white-list \
+  --project-key PROJ \
+  --release-id RELEASE_ID \
+  --recordIDs RECORD_ID \
+  --format json
+
+# Resolve app/chart candidates from the advanced Kubelink layer
+meegle integration kubelink-app-catalog-resolve \
+  --appName APP_NAME \
+  --format json
+```
+
+## Parameter Passing
+
+### Basic Flags
+
+Each command takes parameters via `--flag-name`:
+
+```bash
+meegle workitem get --work-item-id 12345 --project-key PROJ
+```
+
+### Writing `fields[]` (Write Commands)
+
+`workitem create`, `workitem update`, `workflow update-node`, and `subtask update` expect the `fields[]` payload. Pass it through `--params`:
+
+```bash
+--params '{"fields":[
+  {"field_key":"name","field_value":"Title"},
+  {"field_key":"priority","field_value":"P1"}
+]}'
+```
+
+### --set key=value (Generic)
+
+`--set` is an alternate syntax for writing **top-level** parameters — `--set key=value` is equivalent to typing `--key value`. Useful when scripting with a uniform `key=value` form, or for writing nested top-level params via dot-path. Values are auto-typed (int / float / bool / string).
+
+```bash
+# These two are equivalent:
+meegle workitem search-filter --project-key PROJ --work-item-type-keys WORK_ITEM_TYPE_KEY --work-item-name 测试
+meegle workitem search-filter --set project_key=PROJ --set work_item_type_keys=WORK_ITEM_TYPE_KEY --set work_item_name=测试
+
+# Dot-path builds nested maps (rarely used in Meegle, but supported):
+--set extra.flag=true          # becomes {"extra":{"flag":true}}
+```
+
+`--set` only writes **top-level** parameters. To write a work item's `fields[]`, use `--params '{"fields":[...]}'` (see below).
+
+### --params JSON (Fallback)
+
+All commands support `--params` to pass a full JSON parameter body:
+
+```bash
+meegle workitem create --project-key PROJ --work-item-type story \
+  --params '{"fields":[{"field_key":"name","field_value":"Title"}]}'
+```
+
+### Priority
+
+When `--set`, `--params`, and regular flags are used together:
+
+1. Regular CLI flags beat `--params` / `--set` for the same top-level key
+2. `--set` overrides the same top-level key from `--params`
+
+### Array Parameters
+
+Separate multiple values with commas:
+
+```bash
+--user-keys "Alice,Bob,Charlie"
+--field-keys "name,status,priority"
+```
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--format` | `-o` | Output format: `json` (default), `table`, `ndjson`, `raw` |
+| `--select` | | Field projection with dot paths |
+| `--set` | | Set nested parameters (repeatable) |
+| `--params` | `-P` | Full JSON parameter body |
+| `--dry-run` | | Render request without executing |
+| `--verbose` | `-v` | Verbose output |
+| `--profile` | | Use a specific configuration profile |
+
+## Advanced Usage
+
+### Output Formats
+
+```bash
+# JSON (default)
+meegle workitem get --project-key PROJ --work-item-type-key WORK_ITEM_TYPE_KEY --work-item-ids 12345
+
+# NDJSON (suitable for piping)
+meegle workitem +batch-get --project-key PROJ --work-item-ids "12345,12346" -o ndjson
+
+# Table
+meegle workitem search-filter --project-key PROJ --work-item-type-keys WORK_ITEM_TYPE_KEY --work-item-name 测试 -o table
+```
+
+### Field Projection with `--select`
+
+`--select` projects fields using `.` notation. A segment after an array
+broadcasts the remaining path over every record of the array and
+collects the results while preserving the enclosing structure.
+
+| Expression | Response | Projection |
+|---|---|---|
+| `list` | `{"list":[{"a":1}], "total":1}` | `{"list":[{"a":1}]}` |
+| `list.a` | `{"list":[{"a":1,"b":2},{"a":3,"b":4}]}` | `{"list":[{"a":1},{"a":3}]}` |
+| `list.a,list.b` | same as above | `{"list":[{"a":1,"b":2},{"a":3,"b":4}]}` (merged per index) |
+| `list.work_item_info.work_item_name` | `{"list":[{"work_item_info":{"work_item_name":"x"}}]}` | `{"list":[{"work_item_info":{"work_item_name":"x"}}]}` |
+| `nodes.0` | `{"nodes":[{"id":"a"},{"id":"b"}]}` | `{"nodes":{"0":{"id":"a"}}}` (numeric = index) |
+
+```bash
+# Top-level selection
+meegle workitem get \
+  --project-key PROJ \
+  --work-item-type-key WORK_ITEM_TYPE_KEY \
+  --work-item-ids 12345 \
+  --select "data.id,data.name,data.current_nodes"
+
+# Broadcast across arrays — extract fields from nested records
+meegle workitem +batch-get --project-key PROJ --work-item-ids "12345,12346" \
+  --select "results.work_item_id,results.data.name"
+
+# Mix top-level metadata with broadcast
+meegle workitem +batch-get --project-key PROJ --work-item-ids "12345,12346" \
+  --select "summary.total,results.data.name"
+```
+
+### Metadata preservation
+
+The default render preserves the full response shape across every
+`--format`: list endpoints return `{"list":[...], "total":N,
+"pagination":{...}}` verbatim — you see `total` / `pagination` even
+when you do not project them. Drill into records explicitly via
+`--select` (and the broadcast syntax above). Under `--format table`
+and `--format ndjson`, a single-key wrapper like `{"list":[...]}`
+(no sibling metadata) is still peeled into rows — the peel is
+loss-less.
+
+### Dry Run
+
+For commands with side effects, preview the rendered request with `--dry-run` before executing:
+
+```bash
+meegle workitem create --project-key PROJ --work-item-type story \
+  --params '{"fields":[{"field_key":"name","field_value":"Test"}]}' --dry-run
+```
+
+### Command Introspection
+
+Use `inspect` to view full parameter information for any command:
+
+```bash
+# List all commands
+meegle inspect
+
+# View parameters for a specific command
+meegle inspect workitem.create
+```
+
+## Authentication
+
+For this repository's private deployment, ordinary-user authentication normally
+means the remote MCP SSO path shown in [Quick Start](#quick-start):
+
+- run `meegle auth login`
+- the production package uses its built-in production MCP endpoint by default
+- use `meegle config set mcp_server_url ...` only for local debugging or staging overrides
+- inspect the granted identity and scope with `meegle auth whoami`
+
+Run `meegle doctor --format json` after login. If `doctor` fails, stop and fix
+config before running business commands.
+
+Example ordinary-user remote MCP SSO login commands:
+
+```bash
+meegle auth login
+meegle auth whoami --format table
+```
+
+Bootstrap / one-off override example:
+
+```bash
+meegle config set mcp_server_url http://127.0.0.1:62059/mcp
+meegle auth login
+
+# or a one-off endpoint override
+meegle auth login --mcp-server-url https://mcp.example.com/mcp
+meegle auth whoami --format table
+```
+
+### Generic OAuth / Device Code flows
+
+The repository still exposes `meegle auth login` and
+`meegle auth login --device-code`, but those are not the default documented
+workflow for this private deployment. Those flows may still accept
+`--project-key` and persist it when you provide it explicitly, but the private
+deployment default remains remote MCP SSO.
+
+## Configuration
+
+### Config File
+
+Configuration is stored in `~/.meegle/config.json`:
+
+```bash
+# Initialize config
+meegle config init
+
+# View current config
+meegle config show
+
+# Set a config value
+meegle config set host project.feishu.cn
+
+# Get a config value
+meegle config get host
+```
+
+Main config options:
+
+| Field | Description | Examples |
+|-------|-------------|----------|
+| `mcp_server_url` | Optional remote MCP endpoint override for SSO/session flow. Ordinary users should leave it unset when the production package embeds the production endpoint. | `https://mcp.example.com/mcp` |
+| `project_key` | Default collaboration space auto-injected into later commands when they omit `--project-key` | `cbg_product_develop` |
+| `host` | Site domain | `project.feishu.cn`, `meegle.com` |
+| `user_access_token` | User access token; use `${VAR}` to read from an environment variable | `${CI_MEEGLE_TOKEN}` |
+| `access_token_header` | Custom HTTP header name that carries the token; empty falls back to default `Authorization: Bearer <token>` | `x-meegle-auth` |
+| `user_agent` | Caller suffix appended to the default `User-Agent` (form: `meegle-cli/<ver> <user_agent>`); supports `${VAR}` template; overridden by the `MEEGLE_USER_AGENT` env var | `my-service/1.0` |
+
+### Maintainer release checklist
+
+Before publishing the ordinary-user package:
+
+- update `DefaultRemoteMCPServerURL` in `internal/products/meegle/config.go` to the production `/mcp` endpoint
+- build the CLI package with `make meegle-cli`
+- install the staged or published package in a clean shell and run `meegle auth login`
+- confirm `meegle auth whoami --format table` shows the expected account, Meegle user key, projects, and business lines
+- leave `mcp_server_url` unset for ordinary users; use it only for local or staging overrides
+
+### Sandbox / CI: Direct Environment-Variable Injection
+
+For generic token-based CI, these environment variables are also supported:
+
+```bash
+export MEEGLE_HOST=project.feishu.cn
+export MEEGLE_USER_ACCESS_TOKEN=<your-user-token>
+export MEEGLE_USER_AGENT=ci-runner  # optional; appended to User-Agent, highest priority over config.user_agent
+meegle workitem get-brief --work_item_id 123
+```
+
+Either variable may be set independently. When this path is taken, the CLI bypasses the keychain and does not attempt to refresh on 401 — the caller is responsible for rotating the env value.
+
+### Custom Auth Header
+
+By default the token is sent via the standard `Authorization: Bearer <token>` header. If the backend requires a different header (and rejects requests that carry `Authorization`), opt in with `access_token_header`:
+
+```bash
+meegle config set access_token_header x-meegle-auth
+```
+
+Or override at runtime via env var:
+
+```bash
+export MEEGLE_ACCESS_TOKEN_HEADER=x-meegle-auth
+```
+
+When enabled the CLI sends `<header>: <token>` with the raw token (no `Bearer ` prefix) and **omits `Authorization` entirely** — suitable for backends that reject requests carrying both headers.
+
+### Environment Variable Templates
+
+If your runtime exposes a variable with a name other than `MEEGLE_*`, bind it through `config.json` using a `${VAR}` placeholder. The placeholder is resolved against the process environment at runtime. This keeps secrets out of `config.json` while adapting to whatever variable name your runtime (Docker, Kubernetes, CI system) already injects.
+
+```json
+{
+  "current": "prod",
+  "profiles": {
+    "prod":    { "host": "project.feishu.cn", "user_access_token": "${PROD_CI_TOKEN}" },
+    "staging": { "host": "staging.feishu.cn", "user_access_token": "${STAGING_CI_TOKEN}" }
+  }
+}
+```
+
+Rules:
+- Only whole-string placeholders are recognized. `"${X}"` is expanded; `"Bearer ${X}"` is treated as a literal.
+- When a referenced variable is unset or empty, the CLI fails fast and reports the field path and variable name.
+- When `user_access_token` is configured, it takes precedence over any token stored locally by `meegle auth login`. Because this mode has no refresh path, rotate the environment value yourself when the server returns 401.
+
+### Multi-Environment Profiles
+
+Manage multiple environment configurations (different sites, different accounts). Each profile stores its own host and auth credentials independently.
+
+```bash
+# Create a new profile (interactive host selection + login)
+meegle config profile create staging
+
+# List all profiles
+meegle config profile list
+
+# Switch default profile
+meegle config profile use staging
+
+# View current profile
+meegle config profile current
+
+# Temporarily use another profile (without changing default)
+meegle workitem search-filter --project-key PROJ --work-item-type-keys WORK_ITEM_TYPE_KEY --work-item-name 测试 --profile staging
+
+# Delete a profile
+meegle config profile delete staging
+```
+
+## FAQ
+
+### Empty Command List
+
+The CLI fetches available commands from the server at startup. If the network is unreachable or the private runtime is incomplete, dynamic commands won't be registered. Make sure the remote MCP endpoint and session are configured first:
+
+```bash
+meegle doctor --format json
+```
+
+The command list is cached automatically and refreshed silently in the background when expired.
+
+## Security & Risk Warnings
+
+This tool is designed to be called by AI Agents to automate Meegle operations, which carries inherent risks — model hallucinations, unpredictable execution, and prompt injection. Once you authorize Meegle permissions, the Agent will act under your user identity within the granted scope, and may perform high-impact actions (field updates, status transitions, work item creation) on your behalf. Use with care.
+
+Recommended safeguards:
+
+- Preview side-effectful commands with `--dry-run` before running them
+- Use a dedicated profile (`meegle config profile create`) for Agent-driven sessions so you can audit and revoke independently
+- For CI / shared environments, prefer short-lived env-var token injection (`MEEGLE_USER_ACCESS_TOKEN`) and rotate on 401 — do not relax default security settings
+
+By using this tool you are deemed to voluntarily assume all related responsibilities.
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=larksuite/meegle-cli&type=Date)](https://star-history.com/#larksuite/meegle-cli&Date)
+
+## Contributing
+
+Community contributions are welcome. For bugs and feature requests, open an [Issue](https://github.com/larksuite/meegle-cli/issues) or [Pull Request](https://github.com/larksuite/meegle-cli/pulls). For major changes, please start a discussion via an Issue first.
+
+## License
+
+This project is licensed under the **MIT License**.
+
+When running, it calls Lark/Feishu Open Platform APIs. To use these APIs, you must comply with the following agreements and privacy policies:
+
+- [Feishu User Terms of Service](https://www.feishu.cn/terms)
+- [Feishu Privacy Policy](https://www.feishu.cn/privacy)
+- [Feishu Open Platform App Service Provider Security Management Specifications](https://open.feishu.cn/document/uAjLw4CM/uMzNwEjLzcDMx4yM3ATM/management-practice/app-service-provider-security-management-specifications)
+- [Lark User Terms of Service](https://www.larksuite.com/user-terms-of-service)
+- [Lark Privacy Policy](https://www.larksuite.com/privacy-policy)