CLI 参考 — Cloady Docs

cloady 让你在终端里部署和管理应用。它调用的是控制台所用的同一套 REST API，因此你用脚本完成的任何操作，效果都与在界面上逐项点击完全相同。

安装

Terminal

npm install -g cloady

需要 Node 20+。可以这样验证：

Terminal

cloady --version

身份验证

不带参数运行 cloady login 时，它会打开浏览器，显示一个供你核对的代码，并保存授权后返回的令牌：

Terminal

cloady login
# Confirm this code matches:  WXYZ-1234
# logged in as you@example.com

加上 --scope read、--scope deploy 或 --scope full（默认值），可以限制这个令牌能做的操作。

如果想使用你自己创建的令牌，请先在控制台的 Account → API tokens 中创建一个（令牌值 cldy_… 只显示一次），然后把它作为参数传入：

Terminal

cloady login cldy_…

无论哪种方式，令牌都保存在 ~/.config/cloady/config.json 中（文件权限 0600，遵循 $XDG_CONFIG_HOME）。运行 cloady logout 即可删除它。

令牌按以下顺序查找，先找到的生效：

--token <token> 选项
CLOADY_TOKEN 环境变量
已保存的配置文件

CI 小提示：完全不必运行 login，直接在作业环境中设置 CLOADY_TOKEN 即可。

全局选项

所有命令都支持以下选项：

选项	作用
`--token <token>`	仅在本次调用中使用此 API 令牌
`--api-url <url>`	指向另一个 Cloady API；查找顺序与令牌相同：选项 → `CLOADY_CONTROL_PLANE_URL` → 配置文件
`--json`	以 JSON 格式输出原始 API 响应，而不是便于阅读的逐行格式；在脚本中应使用这种模式

出错时，错误会以 error: <code>: <message> 的格式输出到 stderr，并以非零状态码退出，因此 && 命令链和 CI 步骤都能正确识别失败。实际使用中你会遇到的错误有：

错误码	含义	处理方法
`payment_required`	该应用会让工作区超出免费额度，而目前没有绑定银行卡，或银行卡扣款被拒	由工作区所有者在 Account → Billing 中添加银行卡，或者调小应用的规格
`region_required`	多个区域中都存在这个 ID 的应用	传入 `--region`
`not_found`	该工作区和环境中没有这个 ID 的应用	用 `cloady apps <workspace>` 检查

从仓库部署

cloady deploy 是唯一的创建命令；--type 指明代码来自哪里（git、upload 或 catalog）。

Terminal

cloady deploy github.com/your-org/your-repo --type git

不带其他选项时，各项按以下方式确定：

工作区 — 如果你只有一个工作区，就使用它；有多个时，会出现交互式选择器；一个都没有时，CLI 会当场引导你创建一个（填写名称和 ID；新工作区不产生任何费用）。
区域 — 你大多数应用已在运行的区域；如果没有，则使用第一个已就绪的区域。选择区域只决定这个应用在哪里运行。
名称 — 仓库名。
环境 — production。

构建在 Cloady 上进行（自动识别你的技术栈；如果仓库中有 Dockerfile，则使用它），应用通过类似 shop-k7q2v9ze-acme.cloady.io 的 URL 访问：它由应用名、一段短代码和工作区名组成，HTTPS 已为你配置好。预览环境和开发环境的应用也使用同样的格式；这段短代码保证每个应用的 URL 都独一无二。

命令在部署开始后立即返回，并打印应用 ID、状态和 URL；构建会在之后继续进行。工作区连接 GitHub 之后（Settings → Integrations），也可以部署私有仓库。

适用于所有来源类型的选项：

选项	含义	默认值
`--type <type>`	`git` · `upload` · `catalog`	`upload`
`-w, --workspace <id>`	目标工作区	自动检测
`--region <region>`	应用运行的区域	自动检测
`--name <name>`	显示名称；应用 ID 及其 URL 都随之而定	仓库名、文件夹名或模板名
`--env <env>`	`production` · `preview` · `development`	`production`
`--port <port>`	你的服务器监听的端口（如果仓库自带 compose 文件，则忽略此项）	`3000`
`--value <key=value>`	为新应用设置一个环境变量；可重复使用	—
`--branch <branch>`	要构建的 Git 分支（`--type git`）	仓库默认分支
`--subdir <dir>`	构建某个子目录，适用于 monorepo（`--type git`）	仓库根目录

Terminal

cloady deploy github.com/acme/api --type git --name api --env preview --branch develop --port 8080

每个应用只在一个区域和一个环境中运行；在同一工作区的同一环境内，应用名称是唯一的。

部署本地文件夹

不指定 --type 时，cloady deploy 会把当前目录打包成 zip 并上传，无需 git 远程仓库：

Terminal

cloady deploy                     # the current folder
cloady deploy ./services/api      # some other folder

.git、node_modules、.next、dist、.turbo、.venv、venv、__pycache__ 和 .DS_Store 会被跳过。CLI 会打印上传了多少个文件，之后的构建过程与从仓库部署完全相同。除非传入 --name，否则应用以文件夹名命名。

从模板目录安装应用

Terminal

cloady deploy <applicationId> --type catalog

applicationId 是模板目录中的 ID（wordpress、postgres、n8n 等），与控制台 New Application 选择器中显示的 ID 相同。工作区和区域的确定方式与从仓库部署时相同，上面的所有选项也都适用。应用要求填写的设置用 --value 传入；你没有提供的项会使用默认值或自动生成的密钥。

Terminal

cloady deploy wordpress --type catalog -w acme --region eu1 --name blog
cloady deploy postgres  --type catalog -w acme --region eu1 --value POSTGRES_DB=app

查看信息

Terminal

cloady whoami                     # the authenticated user
cloady workspaces                 # your workspaces (alias: ws)
cloady regions                    # every region, with whether it's ready
cloady apps <workspace>           # apps in a workspace
cloady apps <workspace> --env production --region eu1

apps 为每个应用输出一行：ID、状态、区域、环境、名称。加上 --json 可以获取完整对象，包括端点、服务、资源上限和来源。

生命周期

以下命令都接受 <workspace> <appId> 参数，以及 --env（默认 production）和 --region。只要应用 ID 没有歧义，就可以省略区域；如果多个区域中存在相同的 ID，你会收到 region_required 错误，提示你传入区域。

Terminal

cloady start acme blog            # start a stopped app
cloady stop acme blog             # stop it; its data is kept
cloady redeploy acme blog         # rebuild the latest code and roll the containers
cloady restart acme blog          # alias for redeploy
cloady delete acme blog           # delete the app AND its data

delete 会立即执行，不会提示确认，并且会永久删除应用的数据。此操作无法撤销。要修改应用的名称或 URL，请在控制台中重命名：地址会跟随名称变化，所以你永远不需要为了重命名而删除应用。

在容器中运行命令

Terminal

cloady exec <workspace> <appId> --component <name> -- <command…>

在运行中的容器里执行一条一次性命令，并打印其输出。该命令的退出码就是 CLI 的退出码（超时则为 124），通过管道传入的 stdin 也会被转发。

选项	含义
`--component <name>`	必填。在应用的哪个服务中运行（例如 `wordpress`、`db`）
`--cwd <dir>`	工作目录（默认使用容器自身的工作目录）
`--timeout <seconds>`	超过这个时长就放弃（默认 `30`，最大 `300`）
`--env <env>` / `--region <region>`	同上

Terminal

cloady exec acme blog --component wordpress -- wp plugin list
cloady exec acme db --component postgres -- psql -U app -c 'select 1'
echo 'select count(*) from users;' | cloady exec acme db --component postgres -- psql -U app

命令通过 /bin/sh -c 执行，所以如果你希望管道和通配符在容器内求值，请给它们加上引号。过长的输出会被截断，只保留末尾部分，并在 stderr 中附上说明。有两个错误是 exec 特有的：unknown_component 表示应用中没有这个名称的服务（请在控制台中查看该应用的页面）；no_pod 表示当前没有任何东西在运行，请先启动应用。

脚本示例

Terminal

# wait until an app reports running
until cloady apps acme --json | jq -e '.[] | select(.slug=="blog" and .status=="running")' >/dev/null; do sleep 5; done

# redeploy from CI on every push to main
CLOADY_TOKEN=$CI_SECRET_TOKEN cloady redeploy acme api

# list every app across all workspaces
for ws in $(cloady ws --json | jq -r '.[].slug'); do cloady apps "$ws"; done

CLI 没有覆盖的功能，可以直接调用 REST API：同一个令牌，同一个基础 URL。

本页内容