@coze/cli

v0.3.5

Published

4 days ago

Coze CLI - A command-line interface for Coze platform

0High
0Medium
0Low

coze_sdk

coze_plt

coze_bot

@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

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

coze self skill install

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

By default, when no Space ID is configured, the CLI auto-selects the first available space. Install the default-space plugin to instead resolve the default workspace configured on the server for the current organization.

`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

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

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

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

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

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

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

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

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

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

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

# 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

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

# 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

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

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 |

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

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 |

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 for the full auto-upgrade and bundled-skill design.

`coze plugin` — Plugin Management

Manage opt-in CLI plugins. A plugin's feature is enabled only after the plugin is installed; otherwise the CLI behaves exactly as before. "Installing" a plugin simply writes a switch to the local configuration (plugins.<id>.enabled) — no network access required, so these commands work without login.

| Command | Description | | -------------------------------- | ---------------------------------------------------- | | coze plugin list | List all available plugins and their installed status | | coze plugin install <id> | Install (enable) a plugin | | coze plugin uninstall <id> | Uninstall (disable) a plugin |

# List plugins and whether each is installed
coze plugin list

# Enable the default-space plugin
coze plugin install default-space

# Disable it again
coze plugin uninstall default-space

Built-in plugin: `default-space`

Once installed, when you have not explicitly passed --space-id, the CLI resolves the default workspace configured on the server (for the current organization) instead of auto-selecting the first available space.

Resolution priority (highest to lowest):

--space-id command-line flag
Server-side default workspace (when default-space is installed and the organization has one set)
Stored spaceId in configuration
First available space (fallback)

The default workspace is an organization-scoped concept. Under a personal account (no organization context), the plugin does nothing and the CLI falls back to the existing behavior.

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

Environment variables
Command-line --config file
COZE_CONFIG_FILE environment variable file
Project-level config (.cozerc.json in current directory)
Global config (~/.coze/config.json)
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:

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@coze/cli

Installation

Quick Start

Authentication

Commands

coze auth — Authentication

coze organization — Organization Management

coze space — Workspace Management

coze code — Coze Coding

Project

Message

Deploy

Environment Variables

Domain

Skill

Preview

Git

Repo

Database

Model

Tools

coze generate — Media Generation

Image Generation

Audio Generation (TTS)

Video Generation

coze file — File Operations

coze config — Configuration

coze completion — Shell Autocompletion

coze upgrade — CLI Upgrade

Auto-Upgrade

coze plugin — Plugin Management

Built-in plugin: default-space

Other Commands

Global Options

Configuration

Environment Variables

Exit Codes

License

`coze auth` — Authentication

`coze organization` — Organization Management

`coze space` — Workspace Management

`coze code` — Coze Coding

`coze generate` — Media Generation

`coze file` — File Operations

`coze config` — Configuration

`coze completion` — Shell Autocompletion

`coze upgrade` — CLI Upgrade

`coze plugin` — Plugin Management

Built-in plugin: `default-space`