@coze/cli 0.0.4 → 0.1.0-alpha.0f8b9e

package/{LICENSE → 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,503 @@
-# coze-cli
+# @coze/coding-cli
 
-> command-line tool for coze component development
+Coze Coding 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/coding-cli
+```
+
+## Quick Start
+
+```bash
+# 1. Login to your Coze account
+coze auth login --oauth
+
+# 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 -m "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 --oauth
+
+# Non-interactive login with Personal Access Token (for CI/CD)
+coze auth login --token <YOUR_PAT>
+
+# Check current login status
+coze auth status
+
+# Check status in JSON format
+coze auth status --format json
+
+# Logout and clear credentials
+coze auth logout
+```
+
+You can also authenticate via environment variables for CI/CD pipelines:
+
+```bash
+export COZE_API_TOKEN=<YOUR_PAT>
+```
+
+## Commands
+
+### `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 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 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 |
+| `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 -m "Create a chatbot" --type web
+
+# 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` | Query message status and get result when completed |
+| `coze code message cancel` | Cancel an ongoing message |
 
 ```bash
-npm install -g @coze/cli
+# 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`) |
 
-# Usage
+#### Deploy
 
-## Login
+Deploy projects to the production environment. Supports multiple project types including Agent, Workflow, Skill, Web, Mini-program, etc.
 
-The `login` command will open a browser page for you to authorize. After authorization, you can use other commands. 
+| 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
-coze login
+# 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>
 ```
 
-The command will save the token and related registry info to `~/.npmrc` automatically. You can check it in the file.
+#### Environment Variables
 
-## Logout
+Manage project environment variables (Secrets). Supports development and production environments.
 
-The `logout` command will clear the login status.
+| 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
-coze logout
+# 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>
 ```
 
-## Install
+#### Domain
 
-you can install the component by `npm`, `pnpm` or `yarn` directly.
+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 <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
-npm install @coze-kit/xxx
+# 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 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 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
+```
+
+### `coze config` — Configuration
+
+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 <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
+# 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
+# Install shell completion script
+coze completion --setup
+
+# Remove shell completion script
+coze completion --cleanup
+```
+
+## Global Options
+
+| Option | Description |
+|---|---|
+| `-h, --help` | Show help |
+| `-v, --version` | Show version |
+| `--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 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. **Project-level config** (`.cozerc.json` in current directory)
+4. **Global config** (`~/.coze/config.json`)
+5. **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 |
+| `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
+
+```bash
+# Authenticate with a PAT
+export COZE_API_TOKEN=<YOUR_PAT>
+export COZE_ORG_ID=<ORG_ID>
+export COZE_SPACE_ID=<SPACE_ID>
+
+# 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
+
+MIT

package/bin/main

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+const isCompletion = process.argv.includes('--compzsh') ||
+  process.argv.includes('--compbash') ||
+  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');