@coze/cli 0.0.3 → 0.0.5

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Spring (SG) Pte. Ltd.
+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

package/README.md

@@ -1,40 +1,514 @@
-# coze-cli
+# @coze/cli
 
-> command-line tool for coze component development
+Coze CLI — A command-line tool for interacting with [Coze](https://www.coze.cn) services. Manage organizations, workspaces, projects, deployments, and generate media — all from your terminal.
 
-**Currently, it only supports the `cn` region.**
-
-# Installation
+## Installation
 
 ```bash
 npm install -g @coze/cli
 ```
 
+## Quick Start
+
+```bash
+# 1. Login to your Coze account
+coze auth login
+
+# 2. Select your organization
+coze organization list
+coze organization use <org_id>
+
+# 3. Select your workspace
+coze space list
+coze space use <space_id>
+
+# 4. Start using Coze Coding
+coze code project create --message "Build an intelligent assistant" --type web
+```
+
+## Authentication
+
+Before using most commands, you need to authenticate with Coze.
+
+```bash
+# Interactive login via browser (recommended)
+coze auth login
+
+# Check current login status
+coze auth status
+
+# Check status in JSON format
+coze auth status --format json
+
+# 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`  | 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. Supports switching to personal account by omitting the org_id.
+
+| Command                            | Description                                                      |
+| ---------------------------------- | ---------------------------------------------------------------- |
+| `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)  |
+
+Alias: `coze org`
+
+> When switching to a different organization, the saved Space ID will be cleared automatically. If the specified org_id is not found, the command will fail without modifying the configuration.
+
+### `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 |
+| `coze space use <space_id>` | Set the default workspace                      |
+
+### `coze code` — Coze Coding
+
+#### 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 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 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
+
+# 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`         | 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" -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" -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 -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 <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 -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 <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 from text
+coze generate image "A sunset over the mountains"
+
+# 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"
+
+# Save to file
+coze generate audio "Hello" --output-path ./audio.mp3
+
+# 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 first frame / last frame
+coze generate video create "Animate this" --first-frame https://example.com/frame.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 |
+|---|---|---|
+| `--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 |
+| `--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:**
 
-# Usage
+| Option              | Default | Description                     |
+| ------------------- | ------- | ------------------------------- |
+| `--output <format>` | `text`  | Output format: `text` \| `json` |
 
-## Login
+### `coze file` — File Operations
 
-The `login` command will open a browser page for you to authorize. After authorization, you can use other commands. 
+Upload local files to Coze for use as attachments or context in projects.
+
+| Command                   | Description         |
+| ------------------------- | ------------------- |
+| `coze file upload <path>` | Upload a local file |
 
 ```bash
-coze login
+# Upload a file
+coze file upload ./document.pdf
 ```
 
-The command will save the token and related registry info to `~/.npmrc` automatically. You can check it in the file.
+### `coze config` — Configuration
 
-## Logout
+Manage CLI configuration stored in `~/.coze/config.json` (global) and `.cozerc.json` (project-level).
 
-The `logout` command will clear the login status.
+| Command                         | Description                               |
+| ------------------------------- | ----------------------------------------- |
+| `coze config list`              | List all configuration items with sources |
+| `coze config get <keys...>`     | Get one or more configuration values      |
+| `coze config set <key> <value>` | Set a configuration value                 |
+| `coze config delete <keys...>`  | Delete one or more configuration items    |
 
 ```bash
-coze logout
+# 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
 ```
 
-## Install
+### `coze completion` — Shell Autocompletion
 
-you can install the component by `npm`, `pnpm` or `yarn` directly.
+Set up or remove shell autocompletion (supports bash/zsh/fish/powershell).
 
 ```bash
-npm install @coze-kit/xxx
+# 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                                                 |
+| ------------------- | ----------------------------------------------------------- |
+| `-h, --help`        | Show help                                                   |
+| `-v, --version`     | Show version                                                |
+| `--format <fmt>`    | Output format: `json` or `text` (default: `text`)           |
+| `--no-color`        | Disable ANSI color output                                   |
+| `--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 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
+
+The CLI reads configuration from multiple sources with the following priority (highest to lowest):
+
+1. **Environment variables**
+2. **Command-line** **`--config`** **file**
+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_ORG_ID`            | Default Organization ID                             |
+| `COZE_ENTERPRISE_ID`     | Default Enterprise ID                               |
+| `COZE_SPACE_ID`          | Default Space ID                                    |
+| `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
+
+This project is licensed under the **MIT License**. When running, it calls Coze Platform APIs. To use these APls, you must comply with the following agreements and privacy policies:
+
+- [Privacy Policy](https://docs.coze.cn/guides/privacy)
+- [Terms of Service](https://docs.coze.cn/guides/terms-of-service)
+

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

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+const isCompletion =
+  process.argv.includes('--compzsh') ||
+  process.argv.includes('--compbash') ||
+  process.argv.includes('--comppwsh') ||
+  process.argv.includes('--completion') ||
+  process.argv.includes('completion');
+
+if (isCompletion) {
+  process.env.DOTENV_CONFIG_QUIET = 'true';
+}
+
+process.env.NODE_ENV = 'production';
+
+const isDebug = process.argv.includes('--debug');
+
+// 如果不是 debug 模式，默认关闭 dotenv 的所有控制台输出
+if (!isDebug) {
+  process.env.DOTENV_CONFIG_QUIET = 'true';
+}
+
+require('../lib/cli.js');