@coze/cli 0.2.0-alpha.dea2da → 0.2.0-alpha.e81ff3

package/README.md

@@ -31,7 +31,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 +52,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,7 +65,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 (alias: `reset`; same as `use` with no org_id) |
+| `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`
 
@@ -133,7 +133,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)                                                                                       |
@@ -149,6 +149,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.
@@ -372,14 +376,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):**
@@ -388,6 +396,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.
@@ -421,6 +431,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                             |
@@ -442,12 +458,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.
 
@@ -511,6 +541,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                                                |
@@ -614,6 +646,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)
@@ -642,6 +675,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            |
 
@@ -685,14 +719,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
 
@@ -768,6 +803,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 guide` | Sync CLI-bundled skills to your AI tools and keep versions aligned |
+| `coze agent` | Agent-facing Coze APIs backed by Claw project endpoints            |
+
 ## Global Options
 
 | Option              | Description                                                 |
@@ -811,19 +853,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