@coze/cli 0.2.0-alpha.2372ad → 0.2.0-alpha.7e254b

package/README.md

@@ -8,6 +8,12 @@ Coze CLI — A command-line tool for interacting with [Coze](https://www.coze.cn
 npm install -g @coze/cli
 ```
 
+After installation the CLI silently runs `coze self skill install`, which installs the bundled skills to your local AI agents (Claude Code, Trae, Comate, ...). If that step is skipped or fails, run it manually:
+
+```bash
+coze self skill install
+```
+
 ## Quick Start
 
 ```bash
@@ -31,7 +37,7 @@ coze code project create --message "Build an intelligent assistant" --type web
 Before using most commands, you need to authenticate with Coze.
 
 ```bash
-# Interactive login via browser (recommended)
+# Interactive login via browser
 coze auth login
 
 # Check current login status
@@ -52,7 +58,7 @@ Manage the full authentication lifecycle. Supports interactive OAuth login via b
 
 | Command            | Description                                        |
 | ------------------ | -------------------------------------------------- |
-| `coze auth login`  | Interactive login via browser                      |
+| `coze auth login`  | Interactive login via browser (OAuth)              |
 | `coze auth status` | Check current login status and credential validity |
 | `coze auth logout` | Logout and clear stored credentials                |
 
@@ -65,6 +71,7 @@ View and switch organizations to set the default Organization ID for subsequent
 | `coze organization list`           | List all accessible organizations and their enterprises          |
 | `coze organization use <org_id>`   | Set the default organization (auto-saves Enterprise ID)          |
 | `coze organization use`            | Switch to personal account (clears Organization and Enterprise)  |
+| `coze organization unset`          | Clear the organization context (same as `use` with no org_id). `reset` is an alias for `unset`, and `org` is an alias for `organization`, so `coze org unset` / `coze org reset` also work |
 
 Alias: `coze org`
 
@@ -132,7 +139,7 @@ coze code project list --size 20 --has-published
 | `--type <type>`          | Filter by type (can pass multiple times): `agent` \| `workflow` \| `webapp` \| `app` \| `web` \| `miniprogram` \| `assistant` |
 | `--name <name>`          | Filter by project name                                                                                                        |
 | `--has-published`        | Filter by publish status                                                                                                      |
-| `--search-scope <n>`     | Created by (0=All, 1=CreatedByMe, 2=AllWithCollaborator)                                                                      |
+| `--search-scope <n>`     | Created by (0=All, 1=CreateByMe, 2=AllWithCollaborator)                                                                       |
 | `--folder-id <id>`       | Filter by folder                                                                                                              |
 | `--order-type <n>`       | Sort type (0=descending, 1=ascending)                                                                                         |
 | `--order-by <n>`         | Order by (0=updated\_at, 1=created\_at)                                                                                       |
@@ -148,6 +155,10 @@ coze code project list --size 20 --has-published
 
 > Remote import requires prior OAuth authorization via `coze code git auth login`, and imported projects are automatically bound to the source repo.
 
+**Output:** in JSON mode, prints `{ project_id, source, repo?, project_url }` (`repo` is only present for GitHub imports).
+
+> After a successful import, the CLI automatically sends an initialization query to the project's default conversation in the background (same behavior as the Web client). Use `coze code message status -p <projectId>` to check its progress. If sending fails, the import result is not affected — the CLI prints a hint to send it manually.
+
 #### Message
 
 Send and manage chat messages in Coze Coding projects. The project ID is specified on the `message` parent command and shared by all subcommands.
@@ -371,14 +382,18 @@ coze code git auth login
 # Check authorization status
 coze code git auth status
 
+# Check authorization status in a pipeline
+coze code git auth status --format json | jq .status
+
 # Search repos by keyword
 coze code git search --keyword react
 
 # Paginated search
 coze code git search -k react --page 2 --page-size 10
 
-# Revoke authorization
+# Revoke authorization (interactive confirmation; use --force to skip)
 coze code git auth logout
+coze code git auth logout --force
 ```
 
 **`git`** **options (shared by subcommands):**
@@ -387,6 +402,8 @@ coze code git auth logout
 | ----------------------- | ----------------------------------------------------- |
 | `--provider <provider>` | Git service provider: `github` / `gitlab` (default: `github`) |
 
+> `git auth logout` prompts for confirmation in an interactive terminal. In JSON mode or non-interactive terminals, `--force` is required — otherwise the command fails with `E1000`.
+
 #### Repo
 
 Manage remote repository bindings and sync operations for Coze Coding projects.
@@ -420,6 +437,12 @@ coze code repo pull -p <projectId> --conflict-strategy ours
 coze code repo unbind -p <projectId> --force
 ```
 
+**`repo`** **options (shared by subcommands):**
+
+| Option                  | Description                                           |
+| ----------------------- | ----------------------------------------------------- |
+| `--provider <provider>` | Git service provider: `github` / `gitlab` (default: `github`) |
+
 **`repo create`** **options:**
 
 | Option              | Description                             |
@@ -441,12 +464,26 @@ coze code repo unbind -p <projectId> --force
 | `-p, --project-id <projectId>`        | **(required)** Project ID                               |
 | `--conflict-strategy <strategy>`      | Auto conflict resolution: `ours` / `theirs`             |
 
-**`repo unbind`** **options:**
+**`repo push`** **options:**
 
 | Option                         | Description               |
 | ------------------------------ | ------------------------- |
 | `-p, --project-id <projectId>` | **(required)** Project ID |
-| `--force`                      | Skip confirmation prompt  |
+
+**`repo status`** **options:**
+
+| Option                         | Description               |
+| ------------------------------ | ------------------------- |
+| `-p, --project-id <projectId>` | **(required)** Project ID |
+
+**`repo unbind`** **options:**
+
+| Option                         | Description                          |
+| ------------------------------ | ------------------------------------ |
+| `-p, --project-id <projectId>` | **(required)** Project ID            |
+| `--force`                      | Skip confirmation and unbind directly |
+
+> Without `--force`, `repo unbind` prompts for confirmation in an interactive terminal. In JSON mode or non-interactive terminals, `--force` is required — otherwise the command fails with `E1000`.
 
 > `repo push` and `repo pull` are placeholder implementations pending backend wiring — they currently report success without performing a real sync.
 
@@ -510,6 +547,8 @@ coze code db rollback --db-id <id> --timestamp 1713254400000 --confirm
 | `--all`                  | Fetch all databases across pages                    |
 | `--max-pages <maxPages>` | Max pages to fetch in text mode (default: 10)       |
 
+> In JSON mode, the output is a `{ databases, next_cursor_id }` object (without `--all` it contains a single page; with `--all` it aggregates all pages). In text mode, the output is an auto-paginated array of databases.
+
 **`db gen-types`** **options:**
 
 | Option                   | Description                                                |
@@ -613,6 +652,7 @@ coze generate image "A storyboard" --sequential auto --max-images 5
 | `--optimize-prompt-mode <mode>` | `standard` | Prompt optimization mode                     |
 | `--sequential <mode>`           | `disabled` | Group image generation: `auto` \| `disabled` |
 | `--max-images <n>`              | `15`       | Maximum group images (1–15)                  |
+| `--stdin`                       | `false`    | Read prompt from stdin (pipe input)          |
 | `--output-path <path>`          | —          | Directory to save generated images           |
 
 #### Audio Generation (TTS)
@@ -641,6 +681,7 @@ coze generate audio "Hello" --speaker zh_female_xiaohe_uranus_bigtts --audio-for
 | `--speech-rate <n>`    | `0`                              | Speech rate (-50 to 100)                     |
 | `--loudness-rate <n>`  | `0`                              | Loudness (-50 to 100)                        |
 | `--ssml`               | `false`                          | Treat input as SSML instead of plain text    |
+| `--stdin`              | `false`                          | Read prompt from stdin (pipe input)          |
 | `--uid <uid>`          | `cli_user`                       | User UID                                     |
 | `--output-path <path>` | —                                | Directory to save generated audio            |
 
@@ -684,14 +725,15 @@ Use `coze generate video create` to submit generation tasks, and `coze generate
 | `--first-frame <url>` | — | First frame image URL |
 | `--last-frame <url>` | — | Last frame image URL |
 | `--return-last-frame` | `false` | Return last frame URL in output |
+| `--stdin` | `false` | Read prompt from stdin (pipe input) |
 | `--wait` | `false` | Poll until completion instead of returning `taskId` immediately |
 | `--output-path <path>` | — | Directory to save generated video |
 
-**`generate video status`** **options:**
+**`generate video status`** has no command-specific options. Use the global `--format json` flag to output the full response as JSON:
 
-| Option              | Default | Description                     |
-| ------------------- | ------- | ------------------------------- |
-| `--output <format>` | `text`  | Output format: `text` \| `json` |
+```bash
+coze generate video status task_123 --format json
+```
 
 ### `coze file` — File Operations
 
@@ -767,6 +809,13 @@ coze upgrade --tag beta
 | `--force`     | Force upgrade even if already on the latest version    |
 | `--tag <tag>` | Specify the dist-tag to upgrade to (default: `latest`) |
 
+### Other Commands
+
+| Command      | Description                                                       |
+| ------------ | ----------------------------------------------------------------- |
+| `coze self`  | Manage the Coze CLI itself (e.g. `coze self skill` installs CLI-bundled skills to your AI tools and keeps versions aligned) |
+| `coze agent` | Agent-facing Coze APIs backed by Claw project endpoints            |
+
 ## Global Options
 
 | Option              | Description                                                 |
@@ -810,19 +859,14 @@ The CLI reads configuration from multiple sources with the following priority (h
 
 ## Exit Codes
 
-| Code | Name                 | Description                    |
-| ---- | -------------------- | ------------------------------ |
-| `0`  | `SUCCESS`            | Command completed successfully |
-| `1`  | `GENERAL_ERROR`      | General error                  |
-| `2`  | `AUTH_FAILED`        | Authentication failed          |
-| `3`  | `RESOURCE_NOT_FOUND` | Requested resource not found   |
-| `4`  | `INVALID_ARGUMENT`   | Invalid argument or option     |
-| `5`  | `PERMISSION_DENIED`  | Permission denied              |
-| `6`  | `NETWORK_ERROR`      | Network error                  |
-| `7`  | `SERVER_ERROR`       | Server error                   |
-| `8`  | `TIMEOUT`            | Operation timed out            |
-| `9`  | `QUOTA_EXCEEDED`     | Quota exceeded                 |
-| `10` | `CONFLICT`           | Resource conflict              |
+| Code | Name          | Description                                                 |
+| ---- | ------------- | ----------------------------------------------------------- |
+| `0`  | `SUCCESS`     | Command completed successfully                              |
+| `1`  | `FAILURE`     | General failure (resource, quota, network, or server error) |
+| `2`  | `AUTH_ERROR`  | Authentication error (`E2xxx` error codes)                  |
+| `4`  | `INPUT_ERROR` | Invalid argument or input (`E1xxx` error codes)             |
+
+> Business-level error codes — `E3xxx` (resource), `E4xxx` (quota), and `E5xxx` (network/server) — all exit with code `1`. Check the error `code` field in the JSON output (`--format json`) for the specific error code.
 
 ## License
 

package/bin/postinstall.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// ABOUTME: npm postinstall 钩子：安装/升级后静默执行 `coze self skill install`，
+// ABOUTME: 把 CLI 自带 skills 同步给本机 AI agents；失败则降级为提示，绝不阻断安装。
+//
+// 注意：npm >= 7 默认后台执行生命周期脚本并丢弃输出（需 --foreground-scripts
+// 才展示），因此 npm 用户通常看不到本脚本的打印；pnpm、yarn classic 及旧版
+// npm 会正常转发。同步失败时的兜底是运行时的 update-check 中间件：skills
+// 缺失或与 CLI 版本不一致时，任何命令结束后都会提示 `coze self skill install`。
+// 不要在这里检测 process.stdout.isTTY —— 包管理器执行脚本时 stdout 总是
+// pipe，加了等于在所有包管理器下永久静默。
+
+const SYNC_TIMEOUT_MS = 120000;
+
+try {
+  const { existsSync, readFileSync } = require('fs');
+  const { join } = require('path');
+  const { homedir } = require('os');
+  const { spawnSync } = require('child_process');
+
+  // CI 环境不执行同步（不可控环境不写家目录）
+  // 开发仓库内的安装（rush update / pnpm install）也跳过：发布包不含 src/
+  if (process.env.CI || existsSync(join(__dirname, '..', 'src'))) {
+    process.exit(0);
+  }
+
+  const useColor = !process.env.NO_COLOR;
+  const cyan = text => (useColor ? `[36m${text}[0m` : text);
+
+  // 通过包内 CLI 入口走真实的 `coze self skill install` 代码路径（skipAuth，纯本地：
+  // 释放 bundled skills 到 ~/.coze/cli/skills 并软链到已安装的 AI agents）。
+  // 用户改过的 skill 不会被覆盖（sync 默认不带 --force 即阻止）。
+  const result = spawnSync(
+    process.execPath,
+    [join(__dirname, 'main'), 'self', 'skill', 'install'],
+    {
+      stdio: 'ignore',
+      timeout: SYNC_TIMEOUT_MS,
+      env: { ...process.env, DOTENV_CONFIG_QUIET: 'true' },
+    },
+  );
+
+  // sync 被用户改过的 skill 阻止时也会 exit 0（仅告警不写入），
+  // 因此用 lock 里的版本与包版本比对来确认是否真正同步成功
+  let synced = result.status === 0;
+  if (synced) {
+    try {
+      const lock = JSON.parse(
+        readFileSync(
+          join(homedir(), '.coze', 'cli', '.skill-lock.json'),
+          'utf8',
+        ),
+      );
+      synced = lock.cliVersion === require('../package.json').version;
+      // eslint-disable-next-line @coze-arch/no-empty-catch -- unreadable lock means sync did not complete
+    } catch {
+      synced = false;
+    }
+  }
+
+  if (synced) {
+    process.stdout.write(
+      `\nCoze CLI installed. Bundled skills synced to your AI agents (run ${cyan(
+        'coze self skill status',
+      )} to inspect).\n\n`,
+    );
+  } else {
+    process.stdout.write(
+      `\nCoze CLI installed. Run ${cyan(
+        'coze self skill install',
+      )} to sync the bundled skills to your AI agents (Claude Code, Trae, Comate, ...).\n\n`,
+    );
+  }
+  // eslint-disable-next-line @coze-arch/no-empty-catch -- postinstall sync is best-effort and must never block install
+} catch {
+  // postinstall 同步失败不应阻断安装；运行时 update-check 会兜底提示
+}
+process.exit(0);