Coze CLI 命令行工具，用于图片生成、音频生成、视频生成、聊天、工作流执行等。使用场景：用户要求生成AI图片/音频/视频、使用Coze工作流、聊天对话、认证管理时触发。
Coze CLI 技能文档
功能概述
Coze CLI 技能文档是一项面向实际任务的技能，主要用于本文档描述 coze 命令行工具的所有暴露功能及使用示例，供 AI Agent 充分使用 Coze CLI；所有命令都支持以下全局选项；
核心要点
- h, --help；
- v, --version；
- format <fmt>；
使用与执行
输出格式: json 或 text (默认: text )；no-color；禁用 ANSI 颜色输出；config <pat。它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。
结果检查与注意事项
实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。该技能适合用于一次性任务，也可以接入自动化工作流，与其他技能或上层代理配合完成更完整的业务链路；在组合使用时，应明确每一步的输入输出关系，并避免不同步骤之间出现参数冲突。
Coze CLI 技能文档
本文档描述 coze 命令行工具的所有暴露功能及使用示例，供 AI Agent 充分使用 Coze CLI。
快速开始
# 1. 登录 coze auth login # 2. 选择组织 coze organization list coze organization use# 3. 选择工作空间 coze space list coze space use # 4. 开始使用 coze code project create --message "构建智能助手" --type web
全局选项
所有命令都支持以下全局选项:
| 选项 | 描述 |
|---|---|
-h, --help |
显示帮助 |
-v, --version |
显示版本 |
--format |
输出格式: json 或 text (默认: text) |
--no-color |
禁用 ANSI 颜色输出 |
--config |
使用自定义配置文件 |
--org-id |
覆盖默认组织 ID |
--space-id |
覆盖默认工作空间 ID |
--verbose |
启用详细模式 |
--debug |
启用调试模式 |
--log-file |
将日志写入文件 |
--man |
显示完整手册 |
--schema |
输出命令的 JSON Schema |
--commands |
输出子命令列表 |
退出码
| 代码 | 名称 | 描述 |
|---|---|---|
0 |
SUCCESS |
命令成功完成 |
1 |
FAILURE |
一般失败 (资源、配额、网络或服务器错误) |
2 |
AUTH_ERROR |
认证错误 (E2xxx 错误代码) |
4 |
INPUT_ERROR |
无效参数或输入 (E1xxx 错误代码) |
认证管理 (coze auth)
登录
# 交互式登录 (打开浏览器) coze auth login # 检查登录状态 coze auth status # 检查状态 (JSON 格式) coze auth status --format json # 注销 coze auth logout
注意事项:
- OAuth 激活链接和设备码输出在
stderr - 设备码有 10 分钟有效期
- 命令会前台阻塞等待用户完成授权
组织管理 (coze organization)
别名: coze org
# 列出所有可访问的组织 coze organization list # 切换到指定组织 coze organization use# 切换到个人账户 coze organization use coze organization unset # 清除组织上下文 (别名: reset) coze organization unset
切换到不同组织时，保存的空间 ID 会自动清除。
工作空间管理 (coze space)
# 列出当前组织下的所有空间 coze space list # 切换到指定工作空间 coze space use
Coze Coding (coze code)
项目管理 (coze code project)
别名: coze code proj
项目类型: agent | workflow | app | skill | web | miniprogram | assistant
创建项目
# 创建 Web 项目 coze code project create --message "创建聊天机器人" --type web # 创建并等待初始构建完成 coze code project create --message "创建数据仪表板" --type app --wait # 使用 JSON 格式输出 coze code project create --message "构建智能助手" --type web --format json
project create 选项:
| 选项 | 描述 |
|---|---|
--message |
(必需) 自然语言项目描述/需求 |
--type |
(必需) 项目类型 |
--wait |
等待项目创建完成 (包括首次 AI 消息响应) |
--chat-mode |
聊天模式: ask | agent | dangerous_confirm | plan |
--model-name |
项目模型名称 |
--tool-name |
要启用的工具名称 (可多次传递) |
--design |
启用设计向导 |
--org-id |
组织 ID |
--space-id |
空间 ID |
列出项目
# 列出所有项目 coze code project list # 带筛选条件列出 coze code project list --type agent --type workflow coze code project list --name "客服" coze code project list --size 20 --has-published
project list 选项:
| 选项 | 描述 |
|---|---|
--size |
返回的项目数量 (默认: 10) |
--cursor-id |
分页游标 |
--type |
按类型筛选 (可多次传递) |
--name |
按项目名称筛选 |
--has-published |
按发布状态筛选 |
--search-scope |
创建者 (0=全部, 1=我创建的, 2=含协作者) |
--folder-id |
按文件夹筛选 |
--order-type |
排序类型 (0=降序, 1=升序) |
--order-by |
排序依据 (0=更新时间, 1=创建时间) |
--is-fav-filter |
仅筛选收藏 |
获取项目详情
coze code project get
删除项目
coze code project delete
导入项目
# 从 GitHub 导入 coze code project import --source github --repo user/repo # 从本地文件导入 coze code project import --source local --file ./project.zip
列出项目的数据库表
coze code project db list -p
消息管理 (coze code message)
发送消息
# 发送消息 coze code message send "修复登录 bug" -p 123456 # 等待聊天响应后返回 coze code message send "修复登录 bug" -p 123456 --wait # 使用 @ 语法提及本地文件作为上下文上传 coze code message send "重构 @src/utils.ts 使用 async/await" -p 123456 # 通过 stdin 管道传递额外上下文 (需要 --stdin 标志) cat error.log | coze code message send "分析此错误" --stdin -p 123456 # JSON 格式输出 (NDJSON 事件流，必须按行解析) coze code message send "修复登录 bug" -p 123456 --format json
选项:
| 选项 | 描述 |
|---|---|
-p, --project-id |
项目 ID (或环境变量 COZE_PROJECT_ID) |
--wait |
等待聊天响应后返回 (否则后台发送) |
--stdin |
从 stdin 读取额外上下文 (管道输入) |
查询消息状态
# 查询消息状态 coze code message status -p 123456 # JSON 格式 coze code message status -p 123456 --format json
取消消息
coze code message cancel -p 123456
查看对话历史
# 查看历史 coze code message history -p 123456 # 分页 coze code message history -p 123456 --beforecoze code message history -p 123456 --after
部署管理 (coze code deploy)
部署项目
# 部署项目 coze code deploy# 部署并等待完成 coze code deploy --wait # 部署特定提交并同步数据库表到生产环境 coze code deploy --commit-id --table-name users --table-name orders # JSON 格式 coze code deploy --format json
选项:
| 选项 | 描述 |
|---|---|
--commit-id |
提交 ID (省略则查询最新提交) |
--wait |
等待部署完成 (轮询间隔: 3 秒) |
--table-name |
要同步到生产的数据库表名 (可重复) |
--encrypt-deploy |
预加密的环境变量字符串 (用于 Skill 项目) |
--connector-id |
小程序部署渠道的连接器 ID (可重复) |
查询部署状态
# 查询最新部署状态 coze code deploy status# 查询特定部署记录 coze code deploy status --deploy-id # 等待部署完成 coze code deploy status --wait
列出部署历史
coze code deploy list--page-size 10
修复失败部署
# 修复最新失败的部署 coze code deploy fix--wait # 修复特定部署 coze code deploy fix --deploy-id --wait
环境变量管理 (coze code env)
# 列出开发环境变量 (默认) coze code env list -p# 列出生产环境变量 coze code env list -p --env prod # 设置环境变量 coze code env set API_KEY sk-xxxxx -p # 删除环境变量 (操作开发环境) coze code env delete API_KEY -p
域名管理 (coze code domain)
# 列出绑定到项目的所有自定义域名 coze code domain list -p# 添加自定义域名 coze code domain add example.com -p # 移除自定义域名 coze code domain remove example.com -p
技能管理 (coze code skill)
# 列出可用技能 (显示安装状态) coze code skill list -p# 列出个人技能 coze code skill list -p --my # 将技能添加 (挂载) 到项目的默认对话 coze code skill add -p # 从默认对话移除 (卸载) 技能 coze code skill remove -p # 上传本地 .skill 文件作为个人技能 coze code skill upload ./my-skill.skill -p # 永久删除个人技能 (不同于 remove) coze code skill delete -p
预览 (coze code preview)
# 获取项目预览 URL (沙盒初始化需要 1-3 分钟) coze code preview
预览适用于 Web/App 项目类型。Agent、Automation、Skill、小程序和 Assistant 项目无法从 CLI 预览。
Git 集成 (coze code git)
# 授权 GitHub (默认提供商) coze code git auth login # 授权 GitLab coze code git auth login --provider gitlab # 检查授权状态 coze code git auth status # JSON 格式检查状态 coze code git auth status --format json # 搜索仓库 coze code git search --keyword react # 分页搜索 coze code git search -k react --page 2 --page-size 10 # 撤销授权 coze code git auth logout coze code git auth logout --force
仓库管理 (coze code repo)
# 创建私有仓库 coze code repo create --name my-app --private # 创建公开仓库 coze code repo create --name my-app # 绑定仓库到项目 coze code repo bind -p-r user/my-repo # 检查绑定和同步状态 coze code repo status -p # 推送本地更改到远程 coze code repo push -p # 拉取远程更改 coze code repo pull -p # 拉取并自动解决冲突 coze code repo pull -p --conflict-strategy ours # 解绑仓库 coze code repo unbind -p coze code repo unbind -p --force
数据库管理 (coze code db)
# 创建数据库 coze code db create # 列出数据库 coze code db list coze code db list --all # 获取数据库详情 coze code db get --db-id# 执行 SQL coze code db query --db-id --sql "SELECT * FROM users LIMIT 10" # 危险 SQL 需要 --confirm coze code db query --db-id --sql "DROP TABLE old_data" --confirm # 从文件执行 SQL coze code db query --db-id --file ./schema.sql # 生成 TypeScript 类型 coze code db gen-types --db-id coze code db gen-types --db-id --output types/database.ts coze code db gen-types --db-id --include-schema public --include-schema auth # 导出数据库模式 coze code db dump --db-id coze code db dump --db-id --output db/schema.sql coze code db dump --db-id --data-only # 回滚到时间点 coze code db rollback --db-id --timestamp 1713254400000 --confirm # 查看数据库状态 coze code db status --db-id # 删除数据库 coze code db delete --db-id --confirm
模型管理 (coze code model)
# 列出项目可用模型 coze code model list -p# 按项目类型列出模型 coze code model list --type web # 设置默认对话的模型 coze code model set doubao-dev-0213 -p
工具管理 (coze code tools)
# 列出可用工具 (显示启用状态) coze code tools list -p# 启用工具 coze code tools enable enable_image_gen -p # 禁用工具 coze code tools disable enable_image_gen -p
媒体生成 (coze generate)
图像生成
# 从文本生成图像 coze generate image "山脉上的日落" # 保存到特定路径 coze generate image "标志设计" --output-path ./assets # 指定尺寸 coze generate image "未来城市" --size 4K coze generate image "头像" --size 512x512 # 禁用水印 coze generate image "一只猫" --no-watermark # 使用参考图像 coze generate image "类似风格" --image https://example.com/ref.png # 启用分组图像生成 coze generate image "故事板" --sequential auto --max-images 5 # JSON 格式输出 coze generate image "山脉上的日落" --format json
选项:
| 选项 | 默认值 | 描述 |
|---|---|---|
--size |
2K |
图像尺寸: 2K | 4K | WIDTHxHEIGHT |
--no-watermark |
启用 | 禁用水印 |
--image |
— | 参考图像 URL (可重复) |
--response-format |
url |
响应格式: url | b64_json |
--optimize-prompt-mode |
standard |
提示优化模式 |
--sequential |
disabled |
分组图像生成: auto | disabled |
--max-images |
15 |
最大分组图像数 (1-15) |
--stdin |
false |
从 stdin 读取提示 (管道输入) |
--output-path |
— | 保存生成图像的目录 |
音频生成 (TTS)
# 基本文本转语音 coze generate audio "你好，欢迎使用 Coze" # 保存到文件 coze generate audio "你好" --output-path ./audio.mp3 # 使用 SSML 输入 echo "你好 " | coze generate audio --ssml # 自定义说话人 coze generate audio "你好" --speaker zh_female_xiaohe_uranus_bigtts # 自定义音频编码 coze generate audio "你好" --audio-format ogg_opus # 自定义语速和响度 coze generate audio "你好" --speech-rate 20 --loudness-rate 10 # JSON 格式输出 coze generate audio "你好" --format json
选项:
| 选项 | 默认值 | 描述 |
|---|---|---|
--speaker |
zh_female_xiaohe_uranus_bigtts |
语音说话人 |
--audio-format |
mp3 |
音频编码: pcm | mp3 | ogg_opus |
--sample-rate |
24000 |
采样率 |
--speech-rate |
0 |
语速 (-50 到 100) |
--loudness-rate |
0 |
响度 (-50 到 100) |
--ssml |
false |
将输入视为 SSML 而非纯文本 |
--stdin |
false |
从 stdin 读取提示 (管道输入) |
--uid |
cli_user |
用户 UID |
--output-path |
— | 保存生成音频的目录 |
视频生成
# 创建视频生成任务 coze generate video create "一只猫弹钢琴" # 创建任务并等待完成 coze generate video create "跳舞的小猫" --wait # 保存到特定路径 coze generate video create "跳舞的小猫" --wait --output-path ./video.mp4 # 自定义分辨率和宽高比 coze generate video create "风景" --resolution 1080p --ratio 16:9 # 使用首帧/末帧 coze generate video create "动画化" --first-frame https://example.com/frame.png # 禁用水印 coze generate video create "产品展示" --no-watermark # 固定相机位置 coze generate video create "建筑展示" --camerafixed # 不生成音频 coze generate video create "无声动画" --no-generate-audio # 查询任务状态 coze generate video status task_123 # JSON 格式输出 coze generate video create "一只猫弹钢琴" --format json
video create 选项:
| 选项 | 默认值 | 描述 |
|---|---|---|
--callback-url |
— | 任务状态更改的回调 URL |
--resolution |
720p |
分辨率: 480p | 720p | 1080p |
--ratio |
16:9 |
宽高比 (如 16:9, 9:16, 1:1) |
--size |
— | 从 WIDTHxHEIGHT 派生 ratio/resolution |
--duration |
5 |
时长 (秒) (4-12) |
--no-watermark |
启用 | 禁用水印 |
--seed |
— | 可重现性的随机种子 |
--camerafixed |
false |
固定相机位置 (减少运动) |
--no-generate-audio |
生成音频 | 不生成伴随音频 |
--first-frame |
— | 首帧图像 URL |
--last-frame |
— | 末帧图像 URL |
--return-last-frame |
false |
在输出中返回末帧 URL |
--stdin |
false |
从 stdin 读取提示 (管道输入) |
--wait |
false |
轮询直到完成而非立即返回 taskId |
--output-path |
— | 保存生成视频的目录 |
文件操作 (coze file)
# 上传本地文件 coze file upload ./document.pdf # JSON 格式输出 coze file upload ./document.pdf --format json
配置管理 (coze config)
# 列出所有配置及其来源 (env, local, global, default) coze config list # 获取单个配置值 coze config get spaceId # 获取多个配置值 coze config get apiBaseUrl spaceId organizationId # 设置配置值 coze config set spaceId 123456789 # 删除配置键 coze config delete spaceId coze config delete spaceId apiBaseUrl
Shell 自动补全 (coze completion)
# 安装 shell 补全脚本 (支持 bash/zsh/fish/powershell) coze completion --setup # 移除 shell 补全脚本 coze completion --cleanup
CLI 升级 (coze upgrade)
# 升级到最新版本 coze upgrade # 强制检查和升级 coze upgrade --force # 升级到特定标签 coze upgrade --tag beta
自动升级配置
# 仅提示，不自动安装 coze config set upgrade.mode notify # 完全禁用升级检查 coze config set upgrade.mode off # 跟踪 beta 渠道 coze config set upgrade.channel beta
其他命令
# 管理 Coze CLI 本身 coze self skill install # Agent 面向 Coze API coze agent
配置优先级
CLI 从多个来源读取配置，优先级从高到低：
- 环境变量
- 命令行
--config文件 COZE_CONFIG_FILE环境变量文件- 项目级配置 (
.cozerc.json在当前目录) - 全局配置 (
~/.coze/config.json) - 内置默认值
环境变量
| 变量 | 描述 |
|---|---|
COZE_ORG_ID |
默认组织 ID |
COZE_ENTERPRISE_ID |
默认企业 ID |
COZE_SPACE_ID |
默认工作空间 ID |
COZE_PROJECT_ID |
默认项目 ID (用于 message 命令) |
COZE_CONFIG_FILE |
自定义配置文件路径 |
COZE_CONFIG_SCOPE |
配置写入范围: global 或 local |
COZE_CLI_NO_UPDATE_NOTIFIER |
跳过本次升级检查 |
COZE_CLI_NO_SKILL_NOTIFIER |
跳过本次技能检查 |
CI |
CI 环境标识 |
代理配置
如果需要通过代理访问 Coze API:
export HTTPS_PROXY=http://your-proxy:8080 export HTTP_PROXY=http://your-proxy:8080
CLI 会自动识别并使用配置的代理。
错误处理
退出码映射:
- E1xxx → 4 (INPUT_ERROR)
- E2xxx → 2 (AUTH_ERROR)
- E3xxx/E4xxx/E5xxx → 1 (FAILURE)
常见错误处理:
- 退出码
2: 认证类先执行coze auth login重新登录 - 退出码
4: 检查参数拼写和格式 - 退出码
1: 解析 JSON 输出中的具体错误码
核心规则
- 用户明确指定 Coze CLI 时，禁止私自改用别的能力
- 优先使用
--format json获取结构化输出 - 对用户交付结果时，必须回传最终 reply，不要只回状态
- 对用户交付文件时，必须返回在线链接，不要返回本地路径
- 不确定命令用法时，使用
--help或--man查看
文档基于 @coze/cli 版本 0.3.2
目录
热门AI工具
相关专题
Postman身份认证怎么配置
本专题从实际API接口调试场景出发，讲解Postman身份认证的完整配置流程，包括常见认证协议介绍、授权参数设置、访问令牌填写、OAuth 2.0授权及认证失败排查，帮助用户正确完成接口授权与访问验证。
0
2026.11.06
Postman请求头Headers怎么设置
围绕Postman HTTP请求头配置展开，讲解Headers选项的具体使用方式，包括Key和Value参数填写、请求头信息添加、常见Header字段设置及请求头修改方法，帮助用户解决接口调试过程中遇到的请求头配置问题。
0
2026.11.06
Postman接口请求发送教程
详细介绍Postman接口请求的创建与发送方法，涵盖GET和POST请求、URL配置、请求参数、Headers请求头、Body请求体设置以及响应结果查看，帮助用户掌握Postman接口请求的完整操作流程。
0
2026.11.06
DBeaver怎么导入数据
DBeaver数据导入专题，整理Excel、CSV、SQL、TXT等常见文件的数据导入方法，涵盖目标数据库选择、数据表创建、字段映射、数据类型设置及导入参数配置等操作，帮助用户将本地文件中的数据写入数据库，并了解批量导入、重复数据处理和导入失败等常见问题的解决方法。
0
2026.11.05
DBeaver安全防护教程大全
DBeaver安全防护专题，围绕数据库连接安全、账号密码保护和访问权限管理展开，整理SSL/TLS加密连接、SSH隧道、数据库凭据保存及证书验证等配置方法，同时介绍敏感信息保护、远程连接风险和高权限账号使用等注意事项，帮助用户提高数据库日常管理的安全性。
0
2026.11.05
DBeaver连接创建与配置教程
本专题聚焦DBeaver数据库连接配置与管理，覆盖从新建连接、选择数据库类型到填写连接参数和验证连接的完整流程。针对MySQL、PostgreSQL、SQL Server等常见数据库，整理相应的连接设置方法，并提供驱动缺失、认证失败和连接异常等问题的排查方向。
0
2026.11.04
XORM框架结构体映射与表结构同步
本专题围绕XORM框架的结构体映射展开，说明表名与字段的命名策略、xorm标签常用属性、主键自增与时间字段自动填充，并演示Sync2自动建表、增量字段升级、索引声明与反向生成结构体的完整流程。
0
2026.11.04
XORM框架安装配置与数据库连接
本专题聚焦XORM框架的配置与连接环节，拆解MySQL、PostgreSQL、SQLite、SQL Server的DSN写法与驱动选择，讲清连接池参数、多数据源拆分、读写分离与超时重连的处理方式，并补充容器与兼容数据库的适配经验。
0
2026.11.04
XORM框架安装配置与数据库连接
本专题聚焦XORM框架的配置与连接环节，拆解MySQL、PostgreSQL、SQLite、SQL Server的DSN写法与驱动选择，讲清连接池参数、多数据源拆分、读写分离与超时重连的处理方式，并补充容器与兼容数据库的适配经验。
0
2026.11.04
热门下载
相关下载
精品课程
热门推荐
/
最新课程
JavaScript ES5基础线上课程教学
共6课时 | 12.1万人学习
最新ThinkPHP 5.1全球首发视频教程(60天成就PHP大牛线上培训班课)
共79课时 | 161.8万人学习
phpStudy极速入门视频教程
共6课时 | 54.7万人学习
最新文章
