# @coze/cli

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.

## Installation

```bash
npm install -g @coze/cli
```

After installation the CLI silently runs `coze self skill install`, which installs the bundled skills to your local AI agents (Claude Code, Trae, Comate, ...). On a first install this sync can take up to a minute (it detects every AI agent on your machine and copies/links the skills), so the install may appear to pause near the end — this is expected.

> npm 7+ hides lifecycle-script output by default, so you won't see the sync progress. To watch it, install with `--foreground-scripts`:
>
> ```bash
> npm install -g @coze/cli --foreground-scripts
> ```
>
> (pnpm and yarn classic show the progress without any extra flag.)

If that step is skipped or fails, run it manually:

```bash
coze self skill install
```

## 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
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 (OAuth)              |
| `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)  |
| `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`

> 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)                        |
| `coze code project import`             | Import a project from GitHub repo or local zip file    |
| `coze code project db list -p <projectId>` | List the project's database tables                 |

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/requirements in natural language                                   |
| `--type <type>`          | **(required)** Project type: `agent` \| `workflow` \| `app` \| `skill` \| `web` \| `miniprogram` \| `assistant` |
| `--wait`                 | Wait for project creation to complete (also waits for the first AI message response)                  |
| `--chat-mode <chatMode>` | Chat mode: `ask` \| `agent` \| `dangerous_confirm` \| `plan`                                           |
| `--model-name <name>`    | Model name for the project                                                                            |
| `--tool-name <toolName>` | Tool name to enable (can be passed multiple times)                                                    |
| `--design`               | Enable design wizard (auto-enabled when `--chat-mode` is `plan`)                                      |
| `--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=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)                                                                                       |
| `--is-fav-filter`        | Filter favorites only                                                                                         |

**`project import`** **options:**

| Option                  | Description                                                          |
| ----------------------- | ------------------------------------------------------------------- |
| `-s, --source <source>` | **(required)** Import source: `github` \| `local`                   |
| `-r, --repo <fullName>` | Remote repo full name, e.g. `user/repo` (required when source is `github`) |
| `-f, --file <path>`     | Local zip file path, max 500MB (required when source is `local`)    |

> 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.

| 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                          |
| `coze code message history`        | View the conversation history of a project chat    |

```bash
# Send a message to a project
coze code message send "Fix the login bug" -p 123456

# Wait for the chat response before returning
coze code message send "Fix the login bug" -p 123456 --wait

# 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 additional context via stdin (the --stdin flag is required)
cat error.log | coze code message send "Analyze this error" --stdin -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

# View conversation history (paginate with --before / --after)
coze code message history -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`) |

**`message send`** **options:**

| Option     | Description                                                        |
| ---------- | ----------------------------------------------------------------- |
| `--wait`   | Wait for the chat response before returning (otherwise sent in background) |
| `--stdin`  | Read additional context from stdin (pipe input)                   |

**`message history`** **options:**

| Option              | Description                                       |
| ------------------- | ------------------------------------------------- |
| `--after <msg_id>`  | Cursor for fetching newer messages                |
| `--before <msg_id>` | Cursor for fetching older messages                |

#### 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 list <projectId>`          | List deployment history for a project                  |
| `coze code deploy fix <projectId>`           | Fix a failed deployment by sending deploy logs to AI   |

```bash
# Deploy a project
coze code deploy <projectId>

# Deploy and wait for completion
coze code deploy <projectId> --wait

# Deploy a specific commit and sync database tables to production
coze code deploy <projectId> --commit-id <commitId> --table-name users --table-name orders

# Check latest deployment status
coze code deploy status <projectId>

# Check a specific deployment record
coze code deploy status <projectId> --deploy-id <deployHistoryId>

# List deployment history
coze code deploy list <projectId> --page-size 10

# Fix the latest failed deployment with AI
coze code deploy fix <projectId> --wait
```

**`deploy <projectId>`** **options:**

| Option                          | Description                                                                                       |
| ------------------------------- | ------------------------------------------------------------------------------------------------ |
| `--commit-id <commitId>`        | Commit ID (queries the latest commit if omitted)                                                 |
| `--wait`                        | Wait for the deployment to complete (polling interval: 3 seconds)                                |
| `--table-name <tableName...>`   | Database table name(s) to sync to production (variadic / repeatable)                             |
| `--encrypt-deploy <string>`     | Pre-encrypted environment variable string (for Skill projects)                                   |
| `--connector-id <connectorId>`  | Connector ID for mini-program deployment channels, repeatable (e.g. `10000127` WeChat, `10000126` TikTok) |

**`deploy status <projectId>`** **options:**

| Option                  | Description                                              |
| ----------------------- | ------------------------------------------------------- |
| `--deploy-id <deployId>` | Deployment history ID (queries the latest if omitted)  |

> `deploy status` reuses the parent `deploy --wait` flag to poll until the deployment reaches a terminal state.

**`deploy list <projectId>`** **options:**

| Option                      | Description                            |
| --------------------------- | -------------------------------------- |
| `--page-size <pageSize>`    | Number of records per page (default: 10) |
| `--page-token <pageToken>`  | Page token for pagination              |

**`deploy fix <projectId>`** **options:**

| Option                   | Description                                                  |
| ------------------------ | ----------------------------------------------------------- |
| `--deploy-id <deployId>` | Deployment history ID (queries the latest failed if omitted) |
| `--wait`                 | Wait for the fix message response                           |

#### 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 (operates on the dev environment)
coze code env delete API_KEY -p <projectId>
```

> `env list` filters by `--env dev|prod` (default `dev`). `env delete` always targets the dev environment. `env set` is not yet supported for Skill projects.

#### Domain

Manage custom domains for deployed projects.

| Command                                           | Description                                  |
| ------------------------------------------------- | -------------------------------------------- |
| `coze code domain list -p <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                       |

> `domain add` validates the format and accepts a single-level domain such as `example.com`.

#### Skill

Manage skills associated with a project to extend its capabilities.

| Command                                            | Description                                                       |
| -------------------------------------------------- | ---------------------------------------------------------------- |
| `coze code skill list -p <projectId>`              | List available skills (shows installed status)                   |
| `coze code skill add <skillId> -p <projectId>`     | Add (mount) a skill to the project's default conversation        |
| `coze code skill remove <skillId> -p <projectId>`  | Remove (unmount) a skill from the default conversation           |
| `coze code skill upload <filePath> -p <projectId>` | Upload a local `.skill` file as a personal skill                 |
| `coze code skill delete <skillId> -p <projectId>`  | Permanently delete a personal skill (different from `remove`)     |

> `add`/`remove` only mount or unmount a skill on the project's default conversation. `delete` permanently removes the personal skill itself. On naming conflict, `upload` auto-confirms an overwrite.

**`skill list`** **options:**

| Option                 | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `-p, --project-id <id>` | **(required)** Project ID                         |
| `--space-id <spaceId>` | Space ID (reads from config if omitted)            |
| `--my`                 | List personal skills only                          |
| `--page <page>`        | Page number (for personal skills, default: 1)      |
| `--size <size>`        | Page size (for personal skills, default: 20)       |

#### 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>
```

> Preview is available for Web/App project types. Agent, Automation, Skill, Mini-program, and Assistant projects are not previewable from the CLI — use the Web dashboard instead.

#### Git

Manage Git platform integrations including OAuth authorization and repository search. Use `--provider` to specify the Git service provider (default: github).

| Command                          | Description                                          |
| -------------------------------- | ---------------------------------------------------- |
| `coze code git auth login`       | Authorize a Git platform via OAuth (opens browser)   |
| `coze code git auth status`      | Check the current OAuth authorization status         |
| `coze code git auth logout`      | Revoke OAuth authorization for a Git platform        |
| `coze code git search`           | Search repositories on the authorized Git platform   |

```bash
# Authorize GitHub (default provider)
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 (interactive confirmation; use --force to skip)
coze code git auth logout
coze code git auth logout --force
```

**`git`** **options (shared by subcommands):**

| Option                  | Description                                           |
| ----------------------- | ----------------------------------------------------- |
| `--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.

| Command                                             | Description                                             |
| --------------------------------------------------- | ------------------------------------------------------- |
| `coze code repo create --name <name>`               | Create a new repository on the remote Git platform      |
| `coze code repo bind -p <projectId> -r <fullName>`  | Bind a remote repository to a project                   |
| `coze code repo unbind -p <projectId>`              | Unbind the remote repository from a project             |
| `coze code repo push -p <projectId>`                | Push local commits to the bound remote repository       |
| `coze code repo pull -p <projectId>`                | Pull remote changes from the bound repository           |
| `coze code repo status -p <projectId>`              | Show remote repository binding and sync status          |

```bash
# Create a private repository
coze code repo create --name my-app --private

# Bind a repo to a project
coze code repo bind -p <projectId> -r user/my-repo

# Check binding and sync status
coze code repo status -p <projectId>

# Push local changes to remote
coze code repo push -p <projectId>

# Pull remote changes (auto-resolve conflicts keeping local)
coze code repo pull -p <projectId> --conflict-strategy ours

# Unbind repository
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                             |
| ------------------- | --------------------------------------- |
| `-n, --name <name>` | **(required)** Repository name          |
| `--private`          | Create as private repository            |

**`repo bind`** **options:**

| Option                           | Description                                 |
| -------------------------------- | ------------------------------------------- |
| `-p, --project-id <projectId>`   | **(required)** Project ID                   |
| `-r, --repo <fullName>`          | **(required)** Remote repo (e.g. user/repo) |

**`repo pull`** **options:**

| Option                                | Description                                             |
| ------------------------------------- | ------------------------------------------------------- |
| `-p, --project-id <projectId>`        | **(required)** Project ID                               |
| `--conflict-strategy <strategy>`      | Auto conflict resolution: `ours` / `theirs`             |

**`repo push`** **options:**

| Option                         | Description               |
| ------------------------------ | ------------------------- |
| `-p, --project-id <projectId>` | **(required)** Project ID |

**`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.

#### Database

Manage Supabase-backed databases in the current Coze space. Supports the full database lifecycle, SQL execution, TypeScript type generation, schema/data export, and point-in-time rollback. All `db` subcommands accept `--space-id <spaceId>` (reads from context if omitted).

| Command                                             | Description                                            |
| --------------------------------------------------- | ----------------------------------------------------- |
| `coze code db create`                               | Create a new database (name and credentials auto-generated) |
| `coze code db list`                                 | List databases in the current space                   |
| `coze code db get --db-id <id>`                     | Get database details (connection URLs and credentials) |
| `coze code db query --db-id <id> --sql "<sql>"`     | Execute SQL on a database                             |
| `coze code db gen-types --db-id <id>`               | Generate TypeScript types from the database schema    |
| `coze code db dump --db-id <id>`                    | Export database schema (DDL) or data as SQL           |
| `coze code db rollback --db-id <id> --timestamp <ts> --confirm` | Roll back a database to a point in time (PITR) |
| `coze code db status --db-id <id>`                  | Get database status and restore/rollback info         |
| `coze code db delete --db-id <id> --confirm`        | Delete a database (irreversible)                      |

```bash
# Create a database
coze code db create

# List databases (text mode auto-paginates; use --all in JSON mode)
coze code db list --all

# Execute SQL (read from --sql, --file, or stdin)
coze code db query --db-id <id> --sql "SELECT * FROM users LIMIT 10"

# Dangerous SQL (DROP/TRUNCATE/ALTER TABLE/DELETE or UPDATE without WHERE) requires --confirm
coze code db query --db-id <id> --sql "DROP TABLE old_data" --confirm

# Generate TS types (default output: types/database.ts)
coze code db gen-types --db-id <id> --include-schema public --include-schema auth

# Export schema only (default) or data only
coze code db dump --db-id <id> --output db/schema.sql
coze code db dump --db-id <id> --data-only

# Roll back to a timestamp (milliseconds), --confirm required
coze code db rollback --db-id <id> --timestamp 1713254400000 --confirm
```

**`db query`** **options:**

| Option             | Description                                                       |
| ------------------ | ---------------------------------------------------------------- |
| `--db-id <dbId>`   | **(required)** Database ID                                       |
| `--sql <sql>`      | Inline SQL to execute                                            |
| `--file <path>`    | Read SQL from a file                                             |
| `--confirm`        | Confirm execution of dangerous SQL (required in JSON mode)       |

> SQL is read from `--sql`, then `--file`, then stdin. Dangerous operations (`DROP`, `TRUNCATE`, `ALTER TABLE`, `DELETE`/`UPDATE` without `WHERE`) require `--confirm`; in JSON mode they error out without it, while text mode prompts interactively.

**`db list`** **options:**

| Option                   | Description                                          |
| ------------------------ | --------------------------------------------------- |
| `--limit <limit>`        | Number of databases per page, 1–100 (default: 20)   |
| `--cursor <cursorId>`    | Cursor for pagination                               |
| `--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                                                |
| ------------------------ | --------------------------------------------------------- |
| `--db-id <dbId>`         | **(required)** Database ID                                |
| `--output <path>`        | Output file path (default: `types/database.ts`)           |
| `--include-schema <name>` | Schema name, repeatable (default: `public`)              |

**`db dump`** **options:**

| Option                   | Description                                               |
| ------------------------ | -------------------------------------------------------- |
| `--db-id <dbId>`         | **(required)** Database ID                               |
| `--output <path>`        | Output file path (default: `db/schema.sql`)              |
| `--schema-only`          | Export schema only (the default when neither flag is set) |
| `--data-only`            | Export data only                                         |
| `--include-schema <name>` | Schema name, repeatable (default: `public`)             |

**`db rollback`** / **`db delete`** **options:**

| Option                  | Description                                       |
| ----------------------- | ------------------------------------------------ |
| `--db-id <dbId>`        | **(required)** Database ID                       |
| `--timestamp <ts>`      | **(required, rollback only)** Target timestamp in milliseconds |
| `--confirm`             | **(required)** Confirm the destructive operation |

#### Model

Manage the model used by a Coze Coding project's default conversation.

| Command                                             | Description                                     |
| --------------------------------------------------- | ----------------------------------------------- |
| `coze code model list -p <projectId>`               | List available models (marks the active one)    |
| `coze code model list --type <type>`                | List available models for a project type        |
| `coze code model set <modelName> -p <projectId>`    | Set the model for the default conversation      |

```bash
# List available models for a project
coze code model list -p <projectId>

# List models by project type (when no project ID is available)
coze code model list --type web

# Set the conversation model
coze code model set doubao-dev-0213 -p <projectId>
```

#### Tools

Manage the tools enabled on a project's default conversation (e.g. web search, image generation).

| Command                                                | Description                                    |
| ------------------------------------------------------ | ---------------------------------------------- |
| `coze code tools list -p <projectId>`                  | List available tools (shows enabled status)    |
| `coze code tools enable <toolName> -p <projectId>`     | Enable a tool on the default conversation      |
| `coze code tools disable <toolName> -p <projectId>`    | Disable a tool on the default conversation     |

```bash
# List available tools
coze code tools list -p <projectId>

# Enable / disable a tool
coze code tools enable enable_image_gen -p <projectId>
coze code tools disable enable_image_gen -p <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)                  |
| `--stdin`                       | `false`    | Read prompt from stdin (pipe input)          |
| `--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    |
| `--stdin`              | `false`                          | Read prompt from stdin (pipe input)          |
| `--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 |
| `--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`** has no command-specific options. Use the global `--format json` flag to output the full response as JSON:

```bash
coze generate video status task_123 --format 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
```

### `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 (supports bash/zsh/fish/powershell).

```bash
# 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`) |

#### Auto-Upgrade

By default Coze CLI keeps itself up to date: it checks for new versions in the background (throttled, never blocking the current command) and, in `auto` mode, installs the update silently so it takes effect on your **next run**. Behavior is controlled via `coze config set`:

| Config            | Values                          | Default  | Description                                                                                          |
| ----------------- | ------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `upgrade.mode`    | `auto` / `notify` / `off`       | `auto`   | `auto`: silent background upgrade; `notify`: only prompt to run `coze upgrade`; `off`: disable checks |
| `upgrade.channel` | `latest` / `beta` / `alpha` / … | `latest` | npm dist-tag to track                                                                               |

```bash
coze config set upgrade.mode notify    # only prompt, don't auto-install
coze config set upgrade.mode off       # disable upgrade checks entirely
coze config set upgrade.channel beta   # track the beta channel
```

Upgrade checks are automatically skipped in CI (the `CI` env var is set), for dev/local builds, and when `COZE_CLI_NO_UPDATE_NOTIFIER` is set. Version checks are throttled to at most once every **4 hours**; a failed background upgrade is retried at most once every **10 minutes**. In JSON output the hint is attached as `_notice.update` with a ready-to-run `command` field. See [`docs/design/auto-upgrade-and-skill-sync.md`](docs/design/auto-upgrade-and-skill-sync.md) for the full auto-upgrade and bundled-skill design.

### Other Commands

| Command      | Description                                                       |
| ------------ | ----------------------------------------------------------------- |
| `coze self`  | Manage the Coze CLI itself (e.g. `coze self skill` installs CLI-bundled skills to your AI tools and keeps versions aligned) |
| `coze agent` | Agent-facing Coze APIs backed by Claw project endpoints            |

## 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_CLI_NO_UPDATE_NOTIFIER` | Set to any non-empty value to skip the upgrade check for this run (overrides `upgrade.mode`) |
| `COZE_CLI_NO_SKILL_NOTIFIER`  | Set to any non-empty value to suppress the bundled-skill version-mismatch notice            |
| `CI`                     | When set (to any value other than `false`/`0`), auto-skips upgrade checks and skill notices |

## Exit Codes

| 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

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)