@ysicing/plane-cli 1.0.1 → 1.0.2

package/README.md

@@ -1,28 +1,15 @@
 # plane-cli
 
-基于 Plane 外部 API（`/api/v1`）的轻量命令行工具，使用 Node.js 原生能力实现，不依赖第三方包。
+`plane-cli` 是一个基于 Plane 外部 API（`/api/v1`）的命令行工具，用于在终端中管理 workspace、project 和 work item（issue）。
 
-默认输出偏人类可读；如果要给脚本、Agent 或其他自动化系统消费，统一加 `--json`：
+## 特性
 
-```bash
-plane workspace current
-plane workspace current --json
-plane issue get --project <project-id> <issue-id> --json
-```
-
-## 当前状态
-
-这套 CLI 已经在真实 Plane 实例上做过 smoke 验证，当前重点覆盖：
-
-- 认证与 workspace 选择
-- `project` 的查询、创建、更新、成员管理、features 开关
-- `issue/work-item` 的查询、创建、更新
-- `issue` 的 labels、comments、activities、links、relations、attachments
-
-适合：
-
-- 人类直接在终端里操作
-- Agent / 脚本通过 `--json` 消费结果
+- 支持 API Key 配置与账号密码登录
+- 支持多 workspace 选择与切换
+- 支持人类可读输出与结构化 JSON 输出
+- 支持 `project` 查询、创建、更新、成员管理、features 开关
+- 支持 `issue` 查询、创建、更新、labels、comments、activities、links、relations、attachments
+- 支持 `GAEA-25` 这类 issue key 自动解析
 
 ## 安装
 
@@ -30,104 +17,97 @@ plane issue get --project <project-id> <issue-id> --json
 npm install -g @ysicing/plane-cli
 ```
 
-或直接用 `npx`：
+安装完成后可执行命令为：
 
 ```bash
-npx @ysicing/plane-cli --help
+plane
 ```
 
-## 约束
+## 环境要求
 
-- 鉴权方式：`X-Api-Key`
-- 默认面向 `project` 与 `work-item`
-- 暂不提供危险删除命令
+- Node.js 22 或更高版本
 
-## 要求
+## 输出格式
 
-- Node.js 22+
+默认输出为人类可读格式。
 
-## 初始化
+如需供脚本、Agent 或流水线消费，可使用：
 
 ```bash
-node ./src/cli.js config set \
-  --base-url https://plane.example.com \
-  --api-key your-api-key \
-  --workspace your-workspace-slug
-```
-
-也支持环境变量覆盖：
-
-```bash
-export PLANE_BASE_URL=https://plane.example.com
-export PLANE_API_KEY=your-api-key
-export PLANE_WORKSPACE=your-workspace-slug
+plane project ls --json
+plane issue get GAEA-25 --format json
 ```
 
-## 快速开始
+## 认证
 
-如果已经有 API key，最短路径是：
+### 方式一：直接配置 API Key
 
 ```bash
 plane config set \
   --base-url https://plane.example.com \
   --api-key your-api-key \
   --workspace your-workspace-slug
-
-plane me
-plane project ls
 ```
 
-## 登录并自动生成 API Token
+也可通过环境变量提供：
+
+```bash
+export PLANE_BASE_URL=https://plane.example.com
+export PLANE_API_KEY=your-api-key
+export PLANE_WORKSPACE=your-workspace-slug
+```
 
-普通账号密码登录：
+### 方式二：账号密码登录
 
 ```bash
-node ./src/cli.js auth login \
+plane auth login \
   --base-url https://plane.example.com \
   --username you@example.com \
   --password 'your-password'
 ```
 
-LDAP 登录：
+### 方式三：LDAP 登录
 
 ```bash
-node ./src/cli.js auth login \
+plane auth login \
   --base-url https://plane.example.com \
   --ldap \
-  --username your-ldap-account \
+  --username your-ldap-user \
   --password 'your-password'
 ```
 
-如果不想把密码放进命令行：
+如需避免在命令行中直接暴露密码：
 
 ```bash
-printf '%s' 'your-password' | node ./src/cli.js auth login \
+printf '%s' 'your-password' | plane auth login \
   --base-url https://plane.example.com \
   --ldap \
-  --username your-ldap-account \
+  --username your-ldap-user \
   --password-stdin
 ```
 
-如果账号下有多个 workspace，且没有显式传 `--workspace`，CLI 会保存登录态生成的 API token，但不会自动选中 workspace。此时请先查看并选择：
+## Workspace 管理
+
+如账号下存在多个 workspace，建议先查看并选择默认 workspace：
 
 ```bash
-node ./src/cli.js workspace ls
-node ./src/cli.js workspace current
-node ./src/cli.js workspace use <slug>
+plane workspace current
+plane workspace ls
+plane workspace use <slug>
 ```
 
-## 常用命令
+## 命令概览
 
-### Workspace
+### 基础命令
 
 ```bash
+plane --help
 plane me
+plane config list
 plane workspace current
-plane workspace ls
-plane workspace use <slug>
 ```
 
-### Project
+### Project 命令
 
 ```bash
 plane project ls
@@ -143,111 +123,122 @@ plane project members ls --project <project-id>
 plane project members add --project <project-id> --member <user-id> --role member
 
 plane project features get <project-id>
-plane project features enable-all <project-id>
 plane project features set <project-id> --epics on --milestones on --auto-transition on
+plane project features enable-all <project-id>
 ```
 
-### Issue / Work Item
+### Issue / Work Item 命令
+
+`work-item` 是 `issue` 的别名。
 
 ```bash
 plane issue ls --project <project-id>
 plane issue get --project <project-id> <issue-id>
-plane issue key DEMO-123
-plane issue get DEMO-123
+plane issue get GAEA-25
+plane issue key GAEA-25
 plane issue search --query login --workspace-search
 
 plane issue create --project <project-id> --name "First work item"
 plane issue update --project <project-id> <issue-id> --priority high
+```
+
+### Issue Labels
 
+```bash
 plane issue labels ls --project <project-id>
 plane issue labels create --project <project-id> --name backend --color '#ff6600'
+```
 
-plane issue comments ls --project <project-id> <issue-id>
-plane issue comments ls DEMO-123
-plane issue comments add --project <project-id> <issue-id> --html '<p>Need follow-up</p>'
-plane issue comments add DEMO-123 --html '<p>Need follow-up</p>'
-plane issue comments update --project <project-id> <issue-id> <comment-id> --html '<p>Updated</p>'
-
-plane issue activities ls --project <project-id> <issue-id>
-plane issue activities ls DEMO-123
+### Issue Comments
 
-plane issue links ls --project <project-id> <issue-id>
-plane issue links ls DEMO-123
-plane issue links add --project <project-id> <issue-id> --url 'https://example.com/doc'
-plane issue links update --project <project-id> <issue-id> <link-id> --url 'https://example.com/doc-v2'
+```bash
+plane issue comments ls GAEA-25
+plane issue comments add GAEA-25 --html '<p>Need follow-up</p>'
+plane issue comments update GAEA-25 <comment-id> --html '<p>Updated</p>'
+```
 
-plane issue relations ls --project <project-id> <issue-id>
-plane issue relations ls DEMO-123
-plane issue relations add --project <project-id> <issue-id> --relation-type blocking --issues '<other-issue-id>'
+### Issue Activities
 
-plane issue attachments ls --project <project-id> <issue-id>
-plane issue attachments ls DEMO-123
-plane issue attachments upload --project <project-id> <issue-id> --file ./spec.pdf
+```bash
+plane issue activities ls GAEA-25
 ```
 
-`work-item` 是 `issue` 的别名：
+### Issue Links
 
 ```bash
-node ./src/cli.js work-item ls --project <project-id>
+plane issue links ls GAEA-25
+plane issue links add GAEA-25 --url 'https://example.com/doc'
+plane issue links update GAEA-25 <link-id> --url 'https://example.com/doc-v2'
 ```
 
-## AI / Agent 友好约定
+### Issue Relations
 
-- 默认输出是人类可读格式
-- 加 `--json` 或 `--format json` 后，成功结果和错误结果都会变成结构化 JSON
-- 参数缺失、workspace 未选择、API 返回错误时，都会带明确 `message`
+```bash
+plane issue relations ls GAEA-25
+plane issue relations add GAEA-25 --relation-type blocking --issues '<other-issue-id>'
+```
 
-示例：
+### Issue Attachments
 
 ```bash
-plane issue get --project <project-id> <issue-id> --json
-plane project ls --json
+plane issue attachments ls GAEA-25
+plane issue attachments upload GAEA-25 --file ./spec.pdf
 ```
 
-## 使用注意
-
-- 多 workspace 登录后，如果没有显式传 `--workspace`，CLI 不会自动替你选择默认 workspace。先执行 `plane workspace ls`，再执行 `plane workspace use <slug>`。
-- `issue create/update --assignees` 支持传用户 ID、邮箱、或精确全名。CLI 会先读取 workspace 成员再解析成后端需要的 member ID。
-- `project create` 带 `--project-lead` 和 `--default-assignee` 时，CLI 会自动采用“两段式创建”：先建项目，再补一次 update。这是为了兼容部分 Plane 实例的后端校验差异。
-- `project features set`、`issue attachments upload` 这类命令在真实实例上可能会遇到几秒钟的读副本延迟。写入成功后如果立刻回读不到，稍后再查一次通常即可。
-- 当前不提供危险删除命令，也不主动清理服务端 token。
+## 交互与参数约定
 
-## 已验证命令
+### Issue Key 自动解析
 
-在真实 Plane 实例上已验证：
+对于以下命令，若目标是已存在的 issue，可直接使用 `GAEA-25` 这类 key，而无需显式提供 `--project` 与 issue UUID：
 
-- `me`
-- `workspace current/ls/use`
-- `project ls/get/summary/create/update`
-- `project members workspace/ls/add`
-- `project features get/set/enable-all`
-- `issue ls/get/key/search/create/update`
-- `issue labels ls/create`
+- `issue get`
 - `issue comments ls/add/update`
 - `issue activities ls`
 - `issue links ls/add/update`
 - `issue relations ls/add`
 - `issue attachments ls/upload`
 
-## 发布
+### 指定 Assignee
+
+`issue create` 与 `issue update` 的 `--assignees` 支持以下输入形式：
+
+- 用户 ID
+- 邮箱
+- 精确全名
+
+CLI 会自动根据 workspace 成员列表解析为后端所需的 member ID。
 
-当前包名使用 `@ysicing/plane-cli`，因为 `plane-cli` 已被 npm 占用。
+## Help 体系
 
-发布前检查：
+支持以下层级的帮助信息：
 
 ```bash
-npm test
-npm run pack:check
+plane -h
+plane project -h
+plane project features set --help
+plane issue comments add --help
+plane issue attachments upload --help
 ```
 
-发布：
+## 限制说明
+
+- 当前不提供危险删除命令
+- 当前不自动回收服务端 API Token
+- `project members ls` 受限于 Plane `api/v1` 返回结构，仅返回用户资料，不包含完整的 `ProjectMember` 记录字段
+- `project create` 在部分 Plane 实例上对 `project_lead/default_assignee` 的校验较严格，CLI 已采用“两段式创建”兼容该行为
+- `project features set`、`issue attachments upload` 在启用读副本的实例上，可能存在短暂回读延迟
+
+## 发布
+
+当前包名为 `@ysicing/plane-cli`。发布前建议执行：
 
 ```bash
-npm publish
+npm test
+npm run pack:check
 ```
 
-如果本机还没登录 npm：
+发布：
 
 ```bash
-npm login
+npm publish
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ysicing/plane-cli",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "type": "module",
   "description": "Node.js CLI for managing Plane via the external API",
   "license": "UNLICENSED",

package/src/commands/config.js

@@ -21,6 +21,19 @@ function printHelp() {
 `);
 }
 
+function printGetHelp() {
+  console.log(`Usage:
+  plane config get
+  plane config get <baseUrl|apiKey|workspace|knownWorkspaces>
+`);
+}
+
+function printSetHelp() {
+  console.log(`Usage:
+  plane config set [--base-url <url>] [--api-key <key>] [--workspace <slug>]
+`);
+}
+
 export async function runConfigCommand(args, context) {
   const [subcommand = "list", ...rest] = args;
   const path = resolveConfigPath();
@@ -38,7 +51,7 @@ export async function runConfigCommand(args, context) {
 
   if (subcommand === "get") {
     if (rest.includes("--help") || rest.includes("-h") || rest.includes("help")) {
-      printHelp();
+      printGetHelp();
       return;
     }
 
@@ -61,7 +74,7 @@ export async function runConfigCommand(args, context) {
 
   if (subcommand === "set") {
     if (rest.includes("--help") || rest.includes("-h") || rest.includes("help")) {
-      printHelp();
+      printSetHelp();
       return;
     }
 

package/src/commands/issue.js

@@ -295,6 +295,108 @@ function printHelp() {
 `);
 }
 
+function printIssueCommentsHelp() {
+  console.log(`Usage:
+  plane issue comments ls --project <project-id> <issue-id>
+  plane issue comments ls GAEA-25
+  plane issue comments add --project <project-id> <issue-id> --html '<p>comment</p>' [--access <value>]
+  plane issue comments add GAEA-25 --html '<p>comment</p>' [--access <value>]
+  plane issue comments update --project <project-id> <issue-id> <comment-id> --html '<p>comment</p>' [--access <value>]
+  plane issue comments update GAEA-25 <comment-id> --html '<p>comment</p>' [--access <value>]
+`);
+}
+
+function printIssueLinksHelp() {
+  console.log(`Usage:
+  plane issue links ls --project <project-id> <issue-id>
+  plane issue links ls GAEA-25
+  plane issue links add --project <project-id> <issue-id> --url <url> [--title <text>]
+  plane issue links add GAEA-25 --url <url> [--title <text>]
+  plane issue links update --project <project-id> <issue-id> <link-id> --url <url> [--title <text>]
+  plane issue links update GAEA-25 <link-id> --url <url> [--title <text>]
+`);
+}
+
+function printIssueRelationsHelp() {
+  console.log(`Usage:
+  plane issue relations ls --project <project-id> <issue-id>
+  plane issue relations ls GAEA-25
+  plane issue relations add --project <project-id> <issue-id> --relation-type <blocking|blocked_by|duplicate|relates_to|start_before|start_after|finish_before|finish_after> --issues <id1,id2>
+  plane issue relations add GAEA-25 --relation-type <blocking|blocked_by|duplicate|relates_to|start_before|start_after|finish_before|finish_after> --issues <id1,id2>
+`);
+}
+
+function printIssueAttachmentsHelp() {
+  console.log(`Usage:
+  plane issue attachments ls --project <project-id> <issue-id>
+  plane issue attachments ls GAEA-25
+  plane issue attachments upload --project <project-id> <issue-id> --file <path> [--name <filename>] [--type <mime>]
+  plane issue attachments upload GAEA-25 --file <path> [--name <filename>] [--type <mime>]
+`);
+}
+
+function printIssueActivitiesHelp() {
+  console.log(`Usage:
+  plane issue activities ls --project <project-id> <issue-id>
+  plane issue activities ls GAEA-25
+`);
+}
+
+function printIssueLabelsHelp() {
+  console.log(`Usage:
+  plane issue labels ls --project <project-id>
+  plane issue labels create --project <project-id> --name <name> [--color <hex>] [--description <text>] [--parent <label-id>] [--sort-order <n>]
+`);
+}
+
+function printIssueLabelsCreateHelp() {
+  console.log(`Usage:
+  plane issue labels create --project <project-id> --name <name> [--color <hex>] [--description <text>] [--parent <label-id>] [--sort-order <n>]
+`);
+}
+
+function printIssueCommentsAddHelp() {
+  console.log(`Usage:
+  plane issue comments add --project <project-id> <issue-id> --html '<p>comment</p>' [--access <value>]
+  plane issue comments add GAEA-25 --html '<p>comment</p>' [--access <value>]
+`);
+}
+
+function printIssueCommentsUpdateHelp() {
+  console.log(`Usage:
+  plane issue comments update --project <project-id> <issue-id> <comment-id> --html '<p>comment</p>' [--access <value>]
+  plane issue comments update GAEA-25 <comment-id> --html '<p>comment</p>' [--access <value>]
+`);
+}
+
+function printIssueLinksAddHelp() {
+  console.log(`Usage:
+  plane issue links add --project <project-id> <issue-id> --url <url> [--title <text>]
+  plane issue links add GAEA-25 --url <url> [--title <text>]
+`);
+}
+
+function printIssueLinksUpdateHelp() {
+  console.log(`Usage:
+  plane issue links update --project <project-id> <issue-id> <link-id> --url <url> [--title <text>]
+  plane issue links update GAEA-25 <link-id> --url <url> [--title <text>]
+`);
+}
+
+function printIssueRelationsAddHelp() {
+  console.log(`Usage:
+  plane issue relations add --project <project-id> <issue-id> --relation-type <blocking|blocked_by|duplicate|relates_to|start_before|start_after|finish_before|finish_after> --issues <id1,id2>
+  plane issue relations add GAEA-25 --relation-type <blocking|blocked_by|duplicate|relates_to|start_before|start_after|finish_before|finish_after> --issues <id1,id2>
+`);
+}
+
+function printIssueAttachmentsUploadHelp() {
+  console.log(`Usage:
+  plane issue attachments upload --project <project-id> <issue-id> --file <path> [--name <filename>] [--type <mime>]
+  plane issue attachments upload GAEA-25 --file <path> [--name <filename>] [--type <mime>]
+`);
+}
+
 async function runIssueLabelsCommand(issueClient, args, context) {
   const [subcommand, ...rest] = args;
 
@@ -304,7 +406,11 @@ async function runIssueLabelsCommand(issueClient, args, context) {
   }
 
   if (hasHelpFlag(rest)) {
-    printHelp();
+    if (subcommand === "create") {
+      printIssueLabelsCreateHelp();
+      return;
+    }
+    printIssueLabelsHelp();
     return;
   }
 
@@ -368,7 +474,15 @@ async function runIssueCommentsCommand(issueClient, args, context) {
   }
 
   if (hasHelpFlag(rest)) {
-    printHelp();
+    if (subcommand === "add") {
+      printIssueCommentsAddHelp();
+      return;
+    }
+    if (subcommand === "update") {
+      printIssueCommentsUpdateHelp();
+      return;
+    }
+    printIssueCommentsHelp();
     return;
   }
 
@@ -459,7 +573,7 @@ async function runIssueActivitiesCommand(issueClient, args, context) {
   }
 
   if (hasHelpFlag(rest)) {
-    printHelp();
+    printIssueActivitiesHelp();
     return;
   }
 
@@ -503,7 +617,15 @@ async function runIssueLinksCommand(issueClient, args, context) {
   }
 
   if (hasHelpFlag(rest)) {
-    printHelp();
+    if (subcommand === "add") {
+      printIssueLinksAddHelp();
+      return;
+    }
+    if (subcommand === "update") {
+      printIssueLinksUpdateHelp();
+      return;
+    }
+    printIssueLinksHelp();
     return;
   }
 
@@ -583,7 +705,11 @@ async function runIssueRelationsCommand(issueClient, args, context) {
   }
 
   if (hasHelpFlag(rest)) {
-    printHelp();
+    if (subcommand === "add") {
+      printIssueRelationsAddHelp();
+      return;
+    }
+    printIssueRelationsHelp();
     return;
   }
 
@@ -660,7 +786,11 @@ async function runIssueAttachmentsCommand(issueClient, args, context) {
   }
 
   if (hasHelpFlag(rest)) {
-    printHelp();
+    if (subcommand === "upload") {
+      printIssueAttachmentsUploadHelp();
+      return;
+    }
+    printIssueAttachmentsHelp();
     return;
   }
 
@@ -739,6 +869,30 @@ export async function runIssueCommand(args, context) {
   }
 
   if (hasHelpFlag(rest)) {
+    if (subcommand === "labels") {
+      printIssueLabelsHelp();
+      return;
+    }
+    if (subcommand === "comments") {
+      printIssueCommentsHelp();
+      return;
+    }
+    if (subcommand === "activities") {
+      printIssueActivitiesHelp();
+      return;
+    }
+    if (subcommand === "links") {
+      printIssueLinksHelp();
+      return;
+    }
+    if (subcommand === "relations") {
+      printIssueRelationsHelp();
+      return;
+    }
+    if (subcommand === "attachments") {
+      printIssueAttachmentsHelp();
+      return;
+    }
     printHelp();
     return;
   }

package/src/commands/project.js

@@ -129,6 +129,46 @@ function printHelp() {
 `);
 }
 
+function printProjectMembersHelp() {
+  console.log(`Usage:
+  plane project members ls --project <project-id>
+  plane project members workspace
+  plane project members add --project <project-id> --member <user-id> --role <admin|member|guest>
+`);
+}
+
+function printProjectMembersAddHelp() {
+  console.log(`Usage:
+  plane project members add --project <project-id> --member <user-id> --role <admin|member|guest>
+`);
+}
+
+function printProjectFeaturesHelp() {
+  console.log(`Usage:
+  plane project features get <project-id>
+  plane project features set <project-id> [--issue-types on|off] [--epics on|off] [--milestones on|off] [--time-tracking on|off] [--auto-transition on|off] [--auto-assign on|off] [--auto-worklog on|off] [--require-worklog-before-completion on|off]
+  plane project features enable-all <project-id>
+`);
+}
+
+function printProjectFeaturesSetHelp() {
+  console.log(`Usage:
+  plane project features set <project-id> [--issue-types on|off] [--epics on|off] [--milestones on|off] [--time-tracking on|off] [--auto-transition on|off] [--auto-assign on|off] [--auto-worklog on|off] [--require-worklog-before-completion on|off]
+`);
+}
+
+function printProjectCreateHelp() {
+  console.log(`Usage:
+  plane project create --name <name> --identifier <identifier> [--description <text>] [--project-lead <user-id>] [--default-assignee <user-id>]
+`);
+}
+
+function printProjectUpdateHelp() {
+  console.log(`Usage:
+  plane project update <project-id> [--name <name>] [--identifier <identifier>] [--description <text>] [--project-lead <user-id>] [--default-assignee <user-id>]
+`);
+}
+
 async function runProjectMembersCommand(projectClient, args, context) {
   const [subcommand, ...rest] = args;
 
@@ -138,7 +178,11 @@ async function runProjectMembersCommand(projectClient, args, context) {
   }
 
   if (hasHelpFlag(rest)) {
-    printHelp();
+    if (subcommand === "add") {
+      printProjectMembersAddHelp();
+      return;
+    }
+    printProjectMembersHelp();
     return;
   }
 
@@ -204,7 +248,11 @@ async function runProjectFeaturesCommand(projectClient, args, context) {
   }
 
   if (hasHelpFlag(rest)) {
-    printHelp();
+    if (subcommand === "set") {
+      printProjectFeaturesSetHelp();
+      return;
+    }
+    printProjectFeaturesHelp();
     return;
   }
 
@@ -290,6 +338,22 @@ export async function runProjectCommand(args, context) {
   }
 
   if (hasHelpFlag(rest)) {
+    if (subcommand === "members") {
+      printProjectMembersHelp();
+      return;
+    }
+    if (subcommand === "features") {
+      printProjectFeaturesHelp();
+      return;
+    }
+    if (subcommand === "create") {
+      printProjectCreateHelp();
+      return;
+    }
+    if (subcommand === "update") {
+      printProjectUpdateHelp();
+      return;
+    }
     printHelp();
     return;
   }