@coze/cli 0.1.0-alpha.2b156a → 0.1.0-alpha.5276dd

package/README.md

@@ -23,7 +23,7 @@ coze space list
 coze space use <space_id>
 
 # 4. Start using Coze Coding
-coze code project create --message "Build an intelligent assistant" --type web
+coze code project create -m "Build an intelligent assistant" --type web
 ```
 
 ## Authentication
@@ -40,7 +40,10 @@ coze auth login --token <YOUR_PAT>
 # Check current login status
 coze auth status
 
-# Logout
+# Check status in JSON format
+coze auth status --format json
+
+# Logout and clear credentials
 coze auth logout
 ```
 
@@ -54,24 +57,30 @@ export COZE_API_TOKEN=<YOUR_PAT>
 
 ### `coze auth` — Authentication
 
+Manage the full authentication lifecycle. Supports interactive OAuth login via browser and non-interactive login via Personal Access Token (PAT) for CI/CD pipelines.
+
 | 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 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 +90,292 @@ 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 -m "Create a chatbot" --type web
 
-# Supported types: agent, workflow, app, skill, web, miniprogram, assistant
+# Create and wait for the initial build to complete
+coze code project create -m "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 true
 ```
 
+**`project create` options:**
+
+| Option | Description |
+|---|---|
+| `-m, --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 <bool>` | 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) |
+| `--is-fav-filter <bool>` | 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 |
 
+```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>
+```
+
 #### 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 <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
+# 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 format
+coze generate audio "Hello" --speaker zh_female_xiaohe_uranus_bigtts --format ogg_opus
+```
+
+**`generate audio` options:**
+
+| Option | Default | Description |
+|---|---|---|
+| `--speaker <speaker>` | `zh_female_xiaohe_uranus_bigtts` | Voice speaker |
+| `--format <fmt>` | `mp3` | Audio format: `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 |
+| `--output-path <path>` | — | Directory to save generated audio |
+
+#### Video Generation
+
+```bash
+# Generate a video (waits for completion by default)
 coze generate video "A cat playing piano"
 
-# Save to a specific directory
-coze generate image "A logo design" --output-path ./assets
+# Save to a specific path
+coze generate video "A dancing kitten" --output-path ./video.mp4
+
+# Create task only, don't wait for completion
+coze generate video "A dancing kitten" --no-wait
+
+# Custom resolution and aspect ratio
+coze generate video "A landscape" --resolution 1080p --ratio 16:9
+
+# Use reference images
+coze generate video "Animate this" --first-frame https://example.com/frame.png
+coze generate video "In this style" --reference-image https://example.com/ref.png
 ```
 
+**`generate video` options:**
+
+| Option | Default | Description |
+|---|---|---|
+| `--model <model>` | `doubao-seedance-1-5-pro-251215` | Video generation model |
+| `--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 |
+| `--no-wait` | waits | Only create task, don't poll for completion |
+| `--poll-interval <ms>` | `2000` | Polling interval in milliseconds |
+| `--poll-timeout <ms>` | `300000` | Polling timeout in milliseconds (5 min) |
+| `--output-path <path>` | — | Directory to save generated video |
+
 ### `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,20 +383,43 @@ 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 for bash/zsh.
+
 ```bash
-# Set up shell autocompletion
+# Install shell completion script
 coze completion --setup
+
+# Remove shell completion script
+coze completion --cleanup
 ```
 
 ## Global Options
@@ -196,14 +428,17 @@ coze completion --setup
 |---|---|
 | `-h, --help` | Show help |
 | `-v, --version` | Show version |
-| `--format <fmt>` | Output format: `json` or `text` (default: `text`) |
+| `--format <fmt>` | Output format: `json` or `text` (default: `json`) |
 | `--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 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
 
@@ -223,6 +458,23 @@ The CLI reads configuration from multiple sources with the following priority (h
 | `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) |
+
+## 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 |
 
 ## CI/CD Usage
 
@@ -232,8 +484,18 @@ export COZE_API_TOKEN=<YOUR_PAT>
 export COZE_ORG_ID=<ORG_ID>
 export COZE_SPACE_ID=<SPACE_ID>
 
-# Deploy a project
+# Create a project and wait for completion
+coze code project create -m "Build a chatbot" --type web --wait --format json
+
+# Send a message to a project
+export COZE_PROJECT_ID=<PROJECT_ID>
+coze code message send "Fix the authentication module" --format json
+
+# Deploy a project and wait for completion
 coze code deploy <projectId> --wait --format json
+
+# Check deployment status
+coze code deploy status <projectId> --format json
 ```
 
 ## License