# Coze CLI 小白上手指南

憨憨的强酸柠檬

1350人浏览 · 2026-04-09 00:16:34

憨憨的强酸柠檬 · 2026-04-09 00:16:34 发布

更新时间：2026-04-09 适用平台：Windows 10 / Windows 11

一、Coze CLI 是什么？

Coze CLI 是 Coze 平台的命令行工具，通过它你可以在终端里完成：

项目管理（创建、查看、切换项目）
文件上传
工作空间（Space）管理
组织（Organization）切换
媒体生成
自动化配置

简单说，就是不用打开浏览器网页，用命令也能操作 Coze 平台。

二、安装 Coze CLI

2.1 环境要求

Node.js（建议 v18 以上）
npm（随 Node.js 自带）

检查是否已安装：

node --version
npm --version

如果没有版本号，去 Node.js 官网下载安装 LTS 版本（长期支持版）。

2.2 安装命令

打开 PowerShell 或 Windows Terminal，执行：

npm install -g @coze/cli

-g 表示全局安装，一次安装，后续在任何目录都能用。

2.3 验证安装成功

coze --version

看到版本号（例如 0.1.0）即为安装成功。

三、登录授权（必须步骤）

注意：不登录的话，CLI 里所有操作都会提示无权限。

3.1 推荐方式：OAuth 浏览器登录

在终端执行：

coze auth login --oauth

执行后终端会显示：

[INFO] Starting OAuth flow...
[INFO] Please visit https://www.coze.cn/oauth/device-activation?user_code=XXXX-XXXX-XXXX and authorize the application.

3.2 授权步骤（按顺序做）

复制授权链接：把终端里显示的 https://www.coze.cn/oauth/device-activation?user_code=XXXX-XXXX-XXXX 复制到浏览器打开。
在浏览器中授权：用你的 Coze 账号扫码或点击登录，确认授权。
等待终端反馈：浏览器授权完成后，终端会自动显示：
```
[INFO] Authentication successful. Credentials saved.
```

检查登录状态：

coze auth status

正常会显示你的用户信息：

logged_in: true
user.user_id: 你的用户ID
user.user_name: 你的用户名

3.3 退出登录

coze auth logout

四、查看与切换组织（Organization）

登录后，你可能属于多个组织（公司、团队等），可以切换。

4.1 查看所有组织

coze organization list

4.2 切换组织

coze organization use <organization_id>

把 <organization_id> 替换成你要切换的组织 ID（从 list 结果中复制）。

五、查看与切换工作空间（Space）

Space 是 Coze 中的工作空间，类似项目文件夹的概念。

5.1 查看所有空间

coze space list

结果示例：

id                   name         org_id
-------------------  -----------  ------
7391318898757025827  Personal
7572831193885327396  LiveChef

5.2 切换空间

coze space use <space_id>

六、Coze Coding 项目开发（重点！）

这是 Coze CLI 的核心功能——用自然语言就能开发一个完整的 Web 应用或 Agent，不需要写代码！

6.1 基本概念

Coze Coding 项目（又称 Vibe 项目）支持以下类型：

类型	说明
`web`	Web 网页应用
`agent`	AI 智能体
`workflow`	工作流
`app`	APP 应用
`skill`	技能
`miniprogram`	小程序
`assistant`	助手

6.2 创建项目

用自然语言描述你想要什么，AI 自动帮你生成项目：

coze code project create --message "创建一个简单的问候页面，显示你好世界" --type web --wait

参数说明：

--message：用中文描述你想要的项目功能
--type：项目类型，这里选 web
--wait：等 AI 生成完再返回（建议加上，否则可能拿到空结果）

正常返回示例：

[INFO] Creating project...
[DONE] Project created successfully
project_id: 7626411569580179490   ← 记下这个 ID，后续操作都要用到
type: web
assistant_id: 18950561848578

6.3 获取预览地址

创建好项目后，在正式开发过程中可以随时预览页面效果：

coze code preview <project_id>

注意：沙箱初始化需要 1-3 分钟，首次预览请稍等。

返回示例：

[INFO] Sandbox initialization started. Please access the preview URL in 1-3 minutes
preview_url: https://xxxx-xxxx-xxxx.dev.coze.site

复制这个地址到浏览器打开，就能看到你的应用界面。

6.4 与 AI 对话修改项目（核心！）

这是最强大的功能——用自然语言让 AI 帮你改代码！

coze code message send "请在页面上添加一个按钮，点击显示当前时间" -p <project_id>

返回示例：

确认"显示当前时间"按钮功能已经完整实现。

## 当前功能
- ✅ "显示当前时间"按钮（居中显示）
- ✅ 点击按钮后显示当前时间（中文格式）
- ✅ 时间显示在按钮下方
- ✅ 支持深色模式

你可以反复发送消息，每次 AI 都会修改代码并实时生效。相当于有一个 24 小时在线的程序员帮你改代码！

6.5 查看项目列表

coze code project list

会列出当前 Space 下所有 Coze Coding 项目（注意：旧版 Agent/Workflow 项目不在此列表中）。

6.6 部署上线

开发完成后，一键部署到生产环境：

coze code deploy <project_id> --wait

--wait 会自动轮询部署状态，等部署完成再返回。

返回示例：

[INFO] Deploying...
[INFO] Polling deployment status...
status: Succeeded
domain: https://xxxx.coze.site    ← 正式上线地址
commitHash: 40e0cc4cebb6fd6f2647598ee6cbe93959c08d78

复制这个正式地址，分享给任何人访问。

6.7 完整开发流程示例

# 第1步：创建项目（描述需求）
coze code project create --message "做一个待办事项网页，可以添加删除任务" --type web --wait

# 第2步：获取预览地址，浏览器打开看效果
coze code preview <返回的project_id>

# 第3步：跟 AI 说需求，不断调整页面
coze code message send "加一个优先级标记功能" -p <project_id>
coze code message send "再加一个截止日期选择器" -p <project_id>
coze code message send "把背景色改成浅蓝色" -p <project_id>

# 第4步：满意后部署上线
coze code deploy <project_id> --wait

6.8 查看更多 coze code 子命令

coze code --help          # 查看所有子命令
coze code project --help  # 项目管理帮助
coze code message --help  # 消息交互帮助
coze code deploy --help   # 部署帮助

6.9 注意事项

⚠️ 旧版项目不适用 coze code：coze code 是为 Coze Coding 新版项目设计的，旧版 Agent / Workflow 项目（如在 Coze 网页上直接创建的）无法使用 project get、message send 等命令，会报"系统错误"或"资源不存在"。这类项目需要在 Coze 网页端操作。

七、常用命令一览

命令	说明
`coze --help`	查看全局帮助
`coze auth login --oauth`	OAuth 浏览器登录
`coze auth status`	查看登录状态
`coze auth logout`	退出登录
`coze organization list`	列出所有组织
`coze organization use <id>`	切换组织
`coze space list`	列出所有工作空间
`coze space use <id>`	切换工作空间
`coze code project create`	创建新项目
`coze code project list`	列出所有项目
`coze code preview <id>`	获取预览地址
`coze code message send`	向项目发消息
`coze code deploy <id>`	部署到生产环境
`coze file`	文件上传管理
`coze config`	本地配置管理
`coze upgrade`	升级 CLI 到最新版本
`coze completion`	配置终端自动补全（建议配置）