@coze/cli 0.1.0-alpha.5aabeb → 0.1.0-alpha.d26823

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -32,46 +32,45 @@ Before using most commands, you need to authenticate with Coze.
 
 ```bash
 # Interactive login via browser (recommended)
-coze auth login --oauth
-
-# Non-interactive login with Personal Access Token (for CI/CD)
-coze auth login --token <YOUR_PAT>
+coze auth login
 
 # Check current login status
 coze auth status
 
-# Logout
-coze auth logout
-```
+# Check status in JSON format
+coze auth status --format json
 
-You can also authenticate via environment variables for CI/CD pipelines:
-
-```bash
-export COZE_API_TOKEN=<YOUR_PAT>
+# Logout and clear credentials
+coze auth logout
 ```
 
 ## Commands
 
 ### `coze auth` — Authentication
 
+Manage the full authentication lifecycle. Supports interactive OAuth login via browser.
+
 | Command | Description |
 |---|---|
-| `coze auth login --oauth` | Interactive login via browser |
-| `coze auth login --token <PAT>` | Login with a Personal Access Token |
-| `coze auth status` | Check current login status |
+| `coze auth login` | Interactive login via browser |
+| `coze auth status` | Check current login status and credential validity |
 | `coze auth logout` | Logout and clear stored credentials |
 
 ### `coze organization` — Organization Management
 
+View and switch organizations to set the default Organization ID for subsequent commands.
+
 | Command | Description |
 |---|---|
-| `coze organization list` | List all accessible organizations |
-| `coze organization use <org_id>` | Set the default organization |
+| `coze organization list` | List all accessible organizations and their enterprises |
+| `coze organization use <org_id>` | Set the default organization (auto-saves Enterprise ID) |
 
 Alias: `coze org`
 
 ### `coze space` — Workspace Management
 
+View and switch workspaces to set the default Space ID for subsequent commands.
+
 | Command | Description |
 |---|---|
 | `coze space list` | List all spaces under the current organization |
@@ -81,92 +80,308 @@ Alias: `coze org`
 
 #### Project
 
+Manage Coze Coding projects. Supports creating, viewing, listing, and deleting projects across various types.
+
 | Command | Description |
 |---|---|
 | `coze code project create` | Create a new project from natural language description |
-| `coze code project list` | List all projects |
-| `coze code project get <id>` | Get project details |
-| `coze code project delete <id>` | Delete a project |
+| `coze code project list` | List all projects in the current space |
+| `coze code project get <projectId>` | Get project details |
+| `coze code project delete <projectId>` | Delete a project (irreversible) |
+
+Alias: `coze code proj`
 
 ```bash
-# Create an Agent project
-coze code project create --message "Create a customer service bot" --type agent
+# Create a Web project
+coze code project create --message "Create a chatbot" --type web
+
+# Create and wait for the initial build to complete
+coze code project create --message "Create a data dashboard" --type app --wait
 
-# Supported types: agent, workflow, app, skill, web, miniprogram, assistant
+# List projects with filters
+coze code project list --type agent --type workflow
+coze code project list --name "customer service"
+coze code project list --size 20 --has-published
 ```
 
+**`project create` options:**
+
+| Option | Description |
+|---|---|
+| `--message <message>` | **(required)** Project description in natural language |
+| `--type <type>` | **(required)** Project type: `web` \| `app` |
+| `--wait` | Wait for project creation to complete |
+| `--org-id <orgId>` | Organization ID (reads from context if omitted) |
+| `--space-id <spaceId>` | Space ID (reads from context if omitted) |
+
+**`project list` options:**
+
+| Option | Description |
+|---|---|
+| `--size <size>` | Number of projects to return (default: 10) |
+| `--cursor-id <cursorId>` | Cursor for pagination |
+| `--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) |
+| `--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) |
+| `--is-fav-filter` | Filter favorites only |
+
 #### 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.
+
 | Command | Description |
 |---|---|
 | `coze code message send [message]` | Send a prompt message to a project chat |
-| `coze code message status` | Check message status |
+| `coze code message status` | Query message status and get result when completed |
 | `coze code message cancel` | Cancel an ongoing message |
 
 ```bash
 # Send a message to a project
-coze code message send "Fix the login bug" --project-id 123456
+coze code message send "Fix the login bug" -p 123456
+
+# Mention local files with @ syntax for upload as context
+coze code message send "Refactor @src/utils.ts to use async/await" -p 123456
+
+# Mention multiple files
+coze code message send "Compare @src/old.ts and @src/new.ts" -p 123456
 
 # Pipe context via stdin
-cat error.log | coze code message send "Analyze this error" --project-id 123456
+cat error.log | coze code message send "Analyze this error" -p 123456
+
+# Check message status (auto-fetches result when completed)
+coze code message status -p 123456
+
+# Cancel an ongoing message
+coze code message cancel -p 123456
+
+# Use environment variable for project ID
+export COZE_PROJECT_ID=123456
+coze code message send "Hello"
 ```
 
+**`message` options (shared by all subcommands):**
+
+| Option | Description |
+|---|---|
+| `-p, --project-id <id>` | Coze project ID (or env `COZE_PROJECT_ID`) |
+
 #### Deploy
 
+Deploy projects to the production environment. Supports multiple project types including Agent, Workflow, Skill, Web, Mini-program, etc.
+
 | Command | Description |
 |---|---|
 | `coze code deploy <projectId>` | Deploy a project to production |
 | `coze code deploy <projectId> --wait` | Deploy and wait for completion |
 | `coze code deploy status <projectId>` | Check deployment status |
+| `coze code deploy status <projectId> --wait` | Check and wait for deployment to complete |
+
+```bash
+# Deploy a project
+coze code deploy <projectId>
+
+# Deploy and wait for completion
+coze code deploy <projectId> --wait
+
+# Check latest deployment status
+coze code deploy status <projectId>
+
+# Check a specific deployment record
+coze code deploy status <projectId> --deploy-id <deployHistoryId>
+
+# Check and wait for deployment to complete
+coze code deploy status <projectId> --wait
+```
 
 #### Environment Variables
 
+Manage project environment variables (Secrets). Supports development and production environments.
+
 | Command | Description |
 |---|---|
-| `coze code env list` | List environment variables |
-| `coze code env set <key> <value>` | Set an environment variable |
-| `coze code env delete <key>` | Delete an environment variable |
+| `coze code env list -p <projectId>` | List environment variables |
+| `coze code env set <key> <value> -p <projectId>` | Set an environment variable |
+| `coze code env delete <key> -p <projectId>` | Delete an environment variable |
+
+```bash
+# List dev environment variables (default)
+coze code env list -p <projectId>
+
+# List prod environment variables
+coze code env list -p <projectId> --env prod
+
+# Set an environment variable
+coze code env set API_KEY sk-xxxxx -p <projectId>
+
+# Delete an environment variable
+coze code env delete API_KEY -p <projectId>
+```
 
 #### Domain
 
+Manage custom domains for deployed projects.
+
 | Command | Description |
 |---|---|
-| `coze code domain list` | List custom domains |
-| `coze code domain add <domain>` | Add a custom domain |
-| `coze code domain remove <domain>` | Remove a custom domain |
+| `coze code domain list <projectId>` | List all custom domains bound to the project |
+| `coze code domain add <domain> -p <projectId>` | Add a custom domain |
+| `coze code domain remove <domain> -p <projectId>` | Remove a custom domain |
 
 #### Skill
 
+Manage skills associated with a project to extend its capabilities.
+
 | Command | Description |
 |---|---|
-| `coze code skill list` | List skills |
-| `coze code skill add` | Add a skill |
-| `coze code skill remove` | Remove a skill |
+| `coze code skill list -p <projectId>` | List all skills (shows installed status) |
+| `coze code skill add <skillId> -p <projectId>` | Add a skill to the project |
+| `coze code skill remove <skillId> -p <projectId>` | Remove a skill from the project |
 
 #### Preview
 
+Get the sandbox preview URL for a project.
+
 | Command | Description |
 |---|---|
-| `coze code preview` | Preview the project |
+| `coze code preview <projectId>` | Get the project preview URL |
+
+```bash
+# Get the preview URL (sandbox initialization takes 1-3 minutes)
+coze code preview <projectId>
+```
 
 ### `coze generate` — Media Generation
 
+Generate images, audio, and video using Coze AI models. All `generate` subcommands support `--output-path <path>` to save generated media to disk.
+
+#### Image Generation
+
 ```bash
-# Generate an image
+# Generate an image from text
 coze generate image "A sunset over the mountains"
 
-# Generate audio
+# Save to a specific path
+coze generate image "A logo design" --output-path ./assets
+
+# Specify size (2K, 4K, or WIDTHxHEIGHT)
+coze generate image "A futuristic city" --size 4K
+
+# Disable watermark
+coze generate image "A cat" --no-watermark
+
+# Use reference image(s)
+coze generate image "Similar style" --image https://example.com/ref.png
+
+# Enable sequential (group) image generation
+coze generate image "A storyboard" --sequential auto --max-images 5
+```
+
+**`generate image` options:**
+
+| Option | Default | Description |
+|---|---|---|
+| `--size <size>` | `2K` | Image size: `2K` \| `4K` \| `WIDTHxHEIGHT` |
+| `--no-watermark` | enabled | Disable watermark |
+| `--image <url>` | — | Reference image URL (repeatable) |
+| `--response-format <fmt>` | `url` | Response format: `url` \| `b64_json` |
+| `--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) |
+| `--output-path <path>` | — | Directory to save generated images |
+
+#### Audio Generation (TTS)
+
+```bash
+# Basic text-to-speech
 coze generate audio "Hello, welcome to Coze"
 
-# Generate a video
-coze generate video "A cat playing piano"
+# Save to file
+coze generate audio "Hello" --output-path ./audio.mp3
 
-# Save to a specific directory
-coze generate image "A logo design" --output-path ./assets
+# Use SSML input
+echo "<speak>Hello</speak>" | coze generate audio --ssml
+
+# Custom speaker and audio encoding
+coze generate audio "Hello" --speaker zh_female_xiaohe_uranus_bigtts --audio-format ogg_opus
 ```
 
+**`generate audio` options:**
+
+| Option | Default | Description |
+|---|---|---|
+| `--speaker <speaker>` | `zh_female_xiaohe_uranus_bigtts` | Voice speaker |
+| `--audio-format <fmt>` | `mp3` | Audio encoding: `pcm` \| `mp3` \| `ogg_opus` |
+| `--sample-rate <n>` | `24000` | Sample rate |
+| `--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 |
+| `--uid <uid>` | `cli_user` | User UID |
+| `--output-path <path>` | — | Directory to save generated audio |
+
+#### Video Generation
+
+```bash
+# Create a video generation task
+coze generate video create "A cat playing piano"
+
+# Create a task and wait for completion
+coze generate video create "A dancing kitten" --wait
+
+# Save to a specific path
+coze generate video create "A dancing kitten" --wait --output-path ./video.mp4
+
+# Custom resolution and aspect ratio
+coze generate video create "A landscape" --resolution 1080p --ratio 16:9
+
+# Use reference images
+coze generate video create "Animate this" --first-frame https://example.com/frame.png
+coze generate video create "In this style" --reference-image https://example.com/ref.png
+
+# Query task status later
+coze generate video status task_123
+```
+
+Use `coze generate video create` to submit generation tasks, and `coze generate video status <taskId>` to query existing tasks.
+
+**`generate video create` options:**
+
+| Option | Default | Description |
+|---|---|---|
+| `--model <model>` | `doubao-seedance-1-5-pro-251215` | Video generation model |
+| `--callback-url <url>` | — | Callback URL for task status changes |
+| `--resolution <res>` | `720p` | Resolution: `480p` \| `720p` \| `1080p` |
+| `--ratio <ratio>` | `16:9` | Aspect ratio (e.g., `16:9`, `9:16`, `1:1`) |
+| `--size <size>` | — | Derive ratio/resolution from `WIDTHxHEIGHT` |
+| `--duration <seconds>` | `5` | Duration in seconds (4–12) |
+| `--no-watermark` | enabled | Disable watermark |
+| `--seed <seed>` | — | Random seed for reproducibility |
+| `--camerafixed` | `false` | Fix camera position (reduce motion) |
+| `--no-generate-audio` | generates audio | Do not generate accompanying audio |
+| `--first-frame <url>` | — | First frame image URL |
+| `--last-frame <url>` | — | Last frame image URL |
+| `--reference-image <url>` | — | Reference image URL (repeatable) |
+| `--return-last-frame` | `false` | Return last frame URL in output |
+| `--wait` | `false` | Poll until completion instead of returning `taskId` immediately |
+| `--output-path <path>` | — | Directory to save generated video |
+
+**`generate video status` options:**
+
+| Option | Default | Description |
+|---|---|---|
+| `--output <format>` | `text` | Output format: `text` \| `json` |
+
 ### `coze file` — File Operations
 
+Upload local files to Coze for use as attachments or context in projects.
+
+| Command | Description |
+|---|---|
+| `coze file upload <path>` | Upload a local file |
+
 ```bash
 # Upload a file
 coze file upload ./document.pdf
@@ -174,22 +389,65 @@ coze file upload ./document.pdf
 
 ### `coze config` — Configuration
 
-Configuration is stored in `~/.coze/config.json` (global) and `.cozerc.json` (project-level).
+Manage CLI configuration stored in `~/.coze/config.json` (global) and `.cozerc.json` (project-level).
 
 | Command | Description |
 |---|---|
 | `coze config list` | List all configuration items with sources |
-| `coze config get <key>` | Get a configuration value |
+| `coze config get <keys...>` | Get one or more configuration values |
 | `coze config set <key> <value>` | Set a configuration value |
-| `coze config delete <key>` | Delete a configuration item |
+| `coze config delete <keys...>` | Delete one or more configuration items |
+
+```bash
+# List all configurations with their sources (env, local, global, default)
+coze config list
+
+# Get a single config value
+coze config get spaceId
+
+# Get multiple config values
+coze config get apiBaseUrl spaceId organizationId
+
+# Set a configuration value
+coze config set spaceId 123456789
+
+# Delete configuration keys
+coze config delete spaceId
+coze config delete spaceId apiBaseUrl
+```
 
 ### `coze completion` — Shell Autocompletion
 
+Set up or remove shell autocompletion (supports bash/zsh/fish/powershell).
+
 ```bash
-# Set up shell autocompletion
+# Install shell completion script
 coze completion --setup
+
+# Remove shell completion script
+coze completion --cleanup
 ```
 
+### `coze upgrade` — CLI Upgrade
+
+Upgrade Coze CLI to the latest version. Detects the package manager used for the original installation (npm/pnpm/yarn) and runs the appropriate global install command.
+
+```bash
+# Upgrade to latest version
+coze upgrade
+
+# Force check and upgrade
+coze upgrade --force
+
+# Upgrade to a specific tag
+coze upgrade --tag beta
+```
+
+| Option | Description |
+|---|---|
+| `--force` | Force upgrade even if already on the latest version |
+| `--tag <tag>` | Specify the dist-tag to upgrade to (default: `latest`) |
+
 ## Global Options
 
 | Option | Description |
@@ -201,9 +459,12 @@ coze completion --setup
 | `--config <path>` | Use a custom configuration file |
 | `--org-id <id>` | Override the default Organization ID |
 | `--space-id <id>` | Override the default Space ID |
-| `--verbose` | Enable verbose logging |
-| `--debug` | Enable debug mode |
+| `--verbose` | Enable verbose mode with detailed process information |
+| `--debug` | Enable debug mode with all log output for diagnosing issues |
 | `--log-file <path>` | Write logs to a file |
+| `--man` | Show full manual information |
+| `--schema` | Output the command's JSON Schema |
+| `--commands` | Output the list of subcommands |
 
 ## Configuration
 
@@ -211,31 +472,39 @@ The CLI reads configuration from multiple sources with the following priority (h
 
 1. **Environment variables**
 2. **Command-line `--config` file**
-3. **Project-level config** (`.cozerc.json` in current directory)
-4. **Global config** (`~/.coze/config.json`)
-5. **Built-in defaults**
+3. **`COZE_CONFIG_FILE` environment variable file**
+4. **Project-level config** (`.cozerc.json` in current directory)
+5. **Global config** (`~/.coze/config.json`)
+6. **Built-in defaults**
 
 ### Environment Variables
 
 | Variable | Description |
 |---|---|
-| `COZE_API_TOKEN` | Personal Access Token for authentication |
 | `COZE_ORG_ID` | Default Organization ID |
 | `COZE_ENTERPRISE_ID` | Default Enterprise ID |
 | `COZE_SPACE_ID` | Default Space ID |
-
-## CI/CD Usage
-
-```bash
-# Authenticate with a PAT
-export COZE_API_TOKEN=<YOUR_PAT>
-export COZE_ORG_ID=<ORG_ID>
-export COZE_SPACE_ID=<SPACE_ID>
-
-# Deploy a project
-coze code deploy <projectId> --wait --format json
-```
+| `COZE_PROJECT_ID` | Default Project ID (used by `message` commands) |
+| `COZE_CONFIG_FILE` | Custom configuration file path |
+| `COZE_CONFIG_SCOPE` | Config write scope: `global` or `local` |
+| `COZE_AUTO_CHECK_UPDATE` | Enable/disable auto update check: `true` or `false` |
+
+## 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 |
 
 ## License
 
-MIT
+See the [LICENSE](LICENSE.md) file and [THIRD-PARTY-LICENSES](THIRD-PARTY-LICENSES.md) included in the package for full terms, conditions, and third-party notices.

package/THIRD-PARTY-LICENSES.md

@@ -0,0 +1,31 @@
+# @coze/cli THIRD-PARTY LICENSES
+
+**Copyright (c) 2026 ByteDance Ltd. and/or its affiliates**
+
+This project, **@coze/cli**, incorporates components from the open source projects listed below.
+The original copyright notices and the licenses under which ByteDance received such components are set forth below.
+
+## Open Source and Third-Party Components
+
+| Component | License | URL |
+| :--- | :--- | :--- |
+| **chalk** | MIT | [Link](https://www.npmjs.com/package/chalk) |
+| **commander** | MIT | [Link](https://www.npmjs.com/package/commander) |
+| **form-data** | MIT | [Link](https://www.npmjs.com/package/form-data) |
+| **http-proxy-agent** | MIT | [Link](https://www.npmjs.com/package/http-proxy-agent) |
+| **https-proxy-agent** | MIT | [Link](https://www.npmjs.com/package/https-proxy-agent) |
+| **lodash** | MIT | [Link](https://www.npmjs.com/package/lodash) |
+| **mitt** | MIT | [Link](https://www.npmjs.com/package/mitt) |
+| **omelette** | MIT | [Link](https://www.npmjs.com/package/omelette) |
+| **undici** | MIT | [Link](https://www.npmjs.com/package/undici) |
+| **@rollup/plugin-commonjs** | MIT | [Link](https://www.npmjs.com/package/@rollup/plugin-commonjs) |
+| **@rollup/plugin-json** | MIT | [Link](https://www.npmjs.com/package/@rollup/plugin-json) |
+| **@rollup/plugin-node-resolve** | MIT | [Link](https://www.npmjs.com/package/@rollup/plugin-node-resolve) |
+| **@rollup/plugin-sucrase** | MIT | [Link](https://www.npmjs.com/package/@rollup/plugin-sucrase) |
+| **@types/lodash** | MIT | [Link](https://www.npmjs.com/package/@types/lodash) |
+| **@types/node** | MIT | [Link](https://www.npmjs.com/package/@types/node) |
+| **@vitest/coverage-v8** | MIT | [Link](https://www.npmjs.com/package/@vitest/coverage-v8) |
+| **rollup** | MIT | [Link](https://www.npmjs.com/package/rollup) |
+| **sucrase** | MIT | [Link](https://www.npmjs.com/package/sucrase) |
+| **tsx** | MIT | [Link](https://www.npmjs.com/package/tsx) |
+| **vitest** | MIT | [Link](https://www.npmjs.com/package/vitest) |

package/bin/main

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 
-const isCompletion = process.argv.includes('--compzsh') ||
+const isCompletion =
+  process.argv.includes('--compzsh') ||
   process.argv.includes('--compbash') ||
+  process.argv.includes('--comppwsh') ||
   process.argv.includes('--completion') ||
   process.argv.includes('completion');