@coze/cli

Coze CLI — A command-line tool for interacting with Coze services. Manage organizations, workspaces, projects, deployments, and generate media — all from your terminal.

Installation

npm install -g @coze/cli

Quick Start

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

# 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

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

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

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

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

# 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

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

# 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

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

| Option | Default | Description | | ------------------- | ------- | ------------------------------- | | --output <format> | text | Output format: text | json |

coze file — File Operations

Upload local files to Coze for use as attachments or context in projects.

| Command | Description | | ------------------------- | ------------------- | | coze file upload <path> | Upload a local file |

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

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

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

# 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
• Terms of Service