---
name: meegle-cli-usage
description: Trigger when a task mentions meego, meegle, 飞书项目, project.feishu.cn, work items, 工作项, workflow nodes, 流程节点, 状态流转, 节点流转, views, PMO baselines, or related-field searches such as planning_version. Use the meegle CLI shipped in this package instead of raw SDK or guessed API calls for Meego automation, debugging, and analysis. Includes safety rules for write operations (`--yes` in non-interactive environments), view-type resolution, and relation-ID based filtering.
---

# Meegle CLI Usage

Use `meegle` as the default entrypoint for Meegle operations in this package. Prefer invoking the CLI over reconstructing request payloads from memory.

## Trigger Cues

Use this skill when the task text or task metadata mentions any of the following:

- command names: `meego`, `meegle`, `meegle-cli`
- product names: `飞书项目`, `Meego`, `project.feishu.cn`
- object names: `工作项`, `需求`, `缺陷`, `迭代`, `版本`, `视图`
- workflow concepts: `流程节点`, `节点流`, `状态流`, `流转`, `transition`, `node`
- report / analysis concepts: `PMO`, `基线`, `完成率`, `planning_version`

For Openclaw, the deterministic trigger should still be:

- `required_skills: ["meegle-cli-usage"]`

The keywords above are semantic hints. The `required_skills` field is the stable routing hook.

## Quick Start

1. Resolve the command path.
   - Try `meegle --help` first.
   - If `meegle` is not in PATH, use `which meegle` or `npm bin -g`.
   - If working inside this package without a global install, use `node_modules/.bin/meegle`.
2. Resolve the command shape before guessing.
   - Run `meegle --help` or `<subcommand> --help`.
3. Separate read and write intent.
   - Treat read commands as default-safe.
   - Treat write commands as opt-in only.
   - In non-interactive environments, only add `--yes` when the user explicitly approved the write.

## Safety Rules

1. Refuse to add `--yes` implicitly.
2. Prefer read-only discovery before any write.
3. Echo the target scope in reasoning before running a write:
   - `profile`
   - `projectKey`
   - `workItemType`
   - target `id` or `ids`
4. If the task can be solved with `get`, `list`, `search`, or `query`, do that first.

## Choose the Right Command

### Query a view

Do not infer the view type from a page URL.

Always:

1. Run `view list` with the candidate `view_id`
2. Inspect `view_type`
3. Use:
   - `view fix-items` for fixed view (`view_type = 2`)
   - `view panoramic-items` only when the view is not fixed

### Filter by a related field

For fields such as `planning_version` or `planning_sprint`:

1. Do not use `workitem search filter` with `field_value_pairs`
2. Resolve the related work item instance ID first
3. Use `workitem search by-params`
4. Pass the related work item **ID list**, not the display name

This is the most common agent mistake. `field_value_pairs` belongs to create/update flows, not search flows.

### Distinguish relation definitions from instance relation fields

Do not confuse:

1. `config relation ...`
   - manages the relation definition itself
   - for example, whether an `issue -> story` relation rule exists

2. `workitem update --field ...`
   - writes a concrete relation field value on an instance
   - for example, `_field_linked_story=<storyId>`

Rules:

- a relation rule existing does not mean a specific item is already linked
- for instance linking, always write the actual relation field
- for relation fields, pass instance IDs, never names
- the CLI now auto-hydrates `field_type_key` for shortcut relation-field writes to avoid silent no-op updates

### Recover from parameter errors

If a write command returns:

- `API_ERROR` with `err_code = 20006`
- `API_ERROR` with `err_code = 20038`
- `API_ERROR` with `err_code = 50006`

do not continue guessing field values.

Required recovery order:

1. Run `workflow query` if the failure happened in workflow commands
2. Run `workflow required-info` to inspect missing node inputs
3. Run `workitem meta` to inspect field type and `options`
4. Retry using the real field structure

Workflow query rules:

- `workflow query` now auto-detects custom state-flow types; if the backend returns `20026/20027`, CLI reads the work item type config and retries with the correct `flow_type`
- use `--flow-type 1` only as an explicit override when you already know the item is state flow and want deterministic inspection
- for state-flow writes, `workflow state-change` now preflights the target state and readbacks the current state plus `role_owners` after the write

Rules:

- `select / radio`: use real option values, not labels
- relation fields: use instance IDs, not display names
- array fields must be written on the right side, for example `--field planning_version=[123,456]`
- do not use `field_key[]=value`; the CLI rejects that form intentionally
- if a relation-field shortcut write returns `ok` but the value is still missing, verify the actual field key with `workitem meta`; the CLI handles `field_type_key` hydration, but it cannot guess the wrong field key
- prefer CLI-provided `hint_code`, `hints`, and `suggested_command` over inventing a new guess

### Advance a workflow safely

Use `workflow advance` when the user wants to:

- move a work item to a target state such as `closed`
- move a workflow item to a target node such as `analysis` or `end`
- continue a long Meego workflow without manually issuing every node operation

Rules:

1. `workflow advance` is an orchestrator, not a value guesser
2. it may stop with `ADVANCE_BLOCKED` and a `blocker_type`
3. if `required-info` returns `50006`, do not assume the step is impossible; `workflow advance` already downgrades to the real transition attempt
4. if a real blocker remains, do not keep guessing values
5. instead, prepare an explicit `--overrides-file`

Typical blockers:

- `required_fields`
- `required_roles`
- `required_owner`
- `required_schedule`
- `required_subtasks`
- `required_deliverables`
- `permission_denied`
- `intercepted`

When an override is needed, prefer a file such as:

```json
{
  "initiate_review": {
    "fields": [
      {
        "field_key": "priority",
        "field_value": { "value": "2" }
      }
    ]
  },
  "doing": {
    "role_assignee": [
      {
        "role": "RD",
        "owners": ["6981271057759993857"]
      }
    ]
  }
}
```

Then run:

```bash
meegle --profile default --yes workflow advance \
  --project-key 69zyer \
  --type-key story \
  --id <WORK_ITEM_ID> \
  --target-node end \
  --overrides-file /absolute/path/to/workflow-advance-overrides.json \
  --json
```

### Build a PMO baseline

For PMO-style analysis:

1. Resolve the target view
2. Fetch the item IDs from the view
3. Fetch work item details with selected fields
4. Resolve user identifiers into display names
5. Summarize:
   - state distribution
   - owner distribution
   - priority coverage
   - due-date coverage
   - age / stale updates

Do not replace a view-scoped baseline with the whole space backlog unless the user explicitly asks for that.

### Resolve user identifiers for reports

If analysis output contains:

- `owner`
- `role_owners`
- raw `user_key`
- “tech owner id”

do not leave those raw IDs in the final human-facing report.

Use `user resolve` as a standard enrich step:

1. collect all user identifiers from the dataset
2. deduplicate them
3. run `meegle user resolve`
4. render `resolved.display_name`

## Write Operations

Use write commands only after explicit user approval.

Typical write commands:

- `workitem create`
- `workitem update`
- `comment add/update/remove`
- `subtask create/update/remove/operate`
- `workflow state-change`
- `workflow node-operate`

In scripts, CI, or agent runners:

- pass `--yes` only when approved
- expect non-interactive write rejection if `--yes` is missing

For role-linked owners:

- `workflow state-change` supports `--role-owner ROLE=USER1,USER2`
- `workflow node-operate` and `workflow node-update` support `--role-assignee ROLE=USER1,USER2`
- role identifiers may be role id, role name, or role alias
- owner identifiers may be `user_key / email / out_id`

## Use the Bundled Examples

Read [references/command-recipes.md](./references/command-recipes.md) when you need:

- view lookup examples
- fixed view item queries
- version lookup by name
- story lookup by `planning_version`
- workflow advance with overrides
- PMO baseline query order

Use the package examples directly when possible:

- `../../examples/view-list.json`
- `../../examples/view-fix-items.json`
- `../../examples/version-search-filter.json`
- `../../examples/story-by-planning-version.json`
- `../../examples/workflow-advance-overrides.json`