Back to Details

cloudcannon-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

The CloudCannon CLI

CloudCannon CLI

@cloudcannon/cli
has two halves. The local half reads and writes files in the working directory and needs no account. The remote half talks to the CloudCannon API, needs credentials, and acts on live sites.
@cloudcannon/cli
分为本地和远程两部分。本地部分负责读取和写入工作目录中的文件，无需账户。远程部分与 CloudCannon API 通信，需要凭据，并会对线上站点执行操作。

When to use

何时使用

  • Finding out whether a command exists for a task, and what its flags are
  • Authenticating, or setting the CLI up in CI
  • Listing, inspecting, or creating sites and organisations
  • Reading or changing files on a hosted site, and committing those changes
  • Triggering a rebuild, or reading build and sync logs
  • Changing an existing site's build configuration
  • Listing form submissions
  • 了解某项任务是否存在对应命令，以及该命令有哪些参数
  • 进行身份验证，或在 CI 中设置 CLI
  • 列出、检查或创建站点和组织
  • 读取或更改托管站点上的文件，并提交这些更改
  • 触发重新构建，或读取构建和同步日志
  • 更改现有站点的构建配置
  • 列出表单提交

When not to use

何时不应使用

  • Deciding what belongs in 
    cloudcannon.config.yml
     — that is 
    cloudcannon-configuration
    . This skill runs 
    configure
    and 
    validate
    ; that skill owns what their output should say.
  • Running the site locally in CloudCannon — 
    cloudcannon dev
    is covered end to end by 
    cloudcannon-dev-server
    , including the rebuild loop and the 
    /__api
    surface.
  • Calling the CloudCannon API from code — that is 
    cloudcannon-sdk
    . It also owns the surface no command reaches: DAMs, backups, sync history and pulls, site scans, screenshots, provider connections, 
    site.copy
    , 
    site.delete
    .
  • Authoring editable regions or snippets — 
    cloudcannon-visual-editing
     and 
    cloudcannon-snippets
    .
  • 决定 
    cloudcannon.config.yml
    中应包含哪些内容    ——这属于 
    cloudcannon-configuration
    。此 skill 会运行 
    configure
    和 
    validate
    ；该 skill 负责决定这些命令的输出应包含哪些内容。
  • 在 CloudCannon 中本地运行站点——
    cloudcannon-dev-server
     完整涵盖 
    cloudcannon dev
    ，包括重新构建循环和 
    /__api
    接口。
  • 从代码中调用 CloudCannon API——这属于 
    cloudcannon-sdk
    。它还负责 CLI 命令无法覆盖的功能，包括 DAM、备份、同步历史和拉取、站点扫描、截图、provider 连接、
    site.copy
    和 
    site.delete
    。
  • 编写可编辑区域或 snippets——
    cloudcannon-visual-editing
     和 
    cloudcannon-snippets
    。

The rule that costs the most

代价最高的规则

MUST confirm with the user before any command that writes to a hosted site.
Why: the remote half is not a sandbox. 
sites files commit
pushes to the site's real git repository, 
sites rebuild
starts a real build, and 
sites update-build-config
changes how every future build runs. None of them prompt, and none are undone by re-running the command.
The read-only remote commands — every 
list
, every 
get
, every 
print-*
— are safe to run unprompted.
MUST 在执行任何会写入托管站点的命令之前向用户确认。
**原因：**远程部分不是沙箱。
sites files commit
会将内容推送到站点的真实 Git 仓库，
sites rebuild
会启动实际构建，而 
sites update-build-config
会改变此后每次构建的运行方式。这些命令均不会提示确认，重新运行也无法撤销其操作。
只读的远程命令——所有 
list
、
get
和 
print-*
命令——无需提示即可安全运行。

Local and remote

本地与远程

HalfCommandsCredentialsActs on
Local
configure detect-*
, 
configure generate
, 
validate
NoneFiles in the working directory
Local
dev
NoneA built output directory
Remote
orgs
, 
sites
, 
builds
, 
inboxes
, 
login
/
logout
RequiredLive sites over the API
MUST NOT assume a command is local because it reads rather than writes. 
sites files get
reads, but reads it over the API from a hosted site.
部分命令凭据操作对象
本地
configure detect-*
、
configure generate
、
validate
无工作目录中的文件
本地
dev
无构建后的输出目录
远程
orgs
、
sites
、
builds
、
inboxes
、
login
/
logout
需要通过 API 操作线上站点
MUST NOT 仅因为某个命令执行读取操作，就假定它是本地命令。
sites files get
虽然执行读取操作，但它通过 API 从托管站点读取数据。

Requirements

环境要求

Node 24 or newer (the current LTS). Install globally with 
npm i -g @cloudcannon/cli
, or invoke with 
npx @cloudcannon/cli <command>
.
需要 Node 24 或更高版本（当前 LTS）。可使用 
npm i -g @cloudcannon/cli
进行全局安装，或通过 
npx @cloudcannon/cli <command>
调用。

Quick start

快速开始

sh
undefined
sh
undefined

What commands exist, and what flags does one take

What commands exist, and what flags does one take

npx @cloudcannon/cli --help npx @cloudcannon/cli sites files commit --help
npx @cloudcannon/cli --help npx @cloudcannon/cli sites files commit --help

Local: generate and check a configuration

Local: generate and check a configuration

npx @cloudcannon/cli configure generate --auto --initial-site-settings npx @cloudcannon/cli validate
npx @cloudcannon/cli configure generate --auto --initial-site-settings npx @cloudcannon/cli validate

Remote: authenticate, then read

Remote: authenticate, then read

npx @cloudcannon/cli login npx @cloudcannon/cli sites list
undefined
npx @cloudcannon/cli login npx @cloudcannon/cli sites list
undefined

Contents

内容

FileCovers
SKILL.md (this file)Routing, the local/remote split, the live-site rule
commands.mdThe full command surface, and querying 
documentation.json
for exact flags
authentication.mdCredential methods, their precedence, where they are stored, CI setup
editing-sessions.md
sites files
— the staged-changes model, committing, discarding
troubleshooting.mdSymptom → cause → fix
文件涵盖内容
SKILL.md（当前文件）命令路由、本地与远程的划分、线上站点操作规则
commands.md完整命令范围，以及查询 
documentation.json
以获取准确参数的方法
authentication.md凭据方式、优先级、存储位置和 CI 设置
editing-sessions.md
sites files
——暂存更改模型、提交和放弃更改
troubleshooting.md症状 → 原因 → 修复方法

Common mistakes

常见错误

ExcuseReality
"I'll write out the flags for this command from memory."Flags change between releases. Query 
documentation.json
or run 
--help
. See commands.md.
"Build settings can only be changed in the dashboard."
sites update-build-config
changes them for an existing site. See commands.md § Changing build configuration.
"I uploaded the file, so the site has it."An upload lands in an editing session, not the repository. It is not live until committed. See editing-sessions.md.
"The command printed nothing, so it failed."Read commands print JSON to stdout and nothing else. An empty result is an empty array, not an error — check the exit code.
"
--site
needs the UUID."		It accepts a name, ID, UUID, or domain.
误解实际情况
“我会凭记忆写出这个命令的参数。”参数会随版本发生变化。请查询 
documentation.json
或运行 
--help
。参见 commands.md。
“构建设置只能在 dashboard 中修改。”
sites update-build-config
可以修改现有站点的构建设置。参见 commands.md § 更改构建配置。
“我已经上传文件，所以站点上已经有这个文件了。”上传的文件会进入 editing session，而不是仓库。在提交之前，它不会正式生效。参见 editing-sessions.md。
“命令没有输出，所以执行失败了。”读取命令只会将 JSON 输出到标准输出，不输出其他内容。空结果表示空数组，而不是错误——请检查退出代码。
“
--site
需要使用 UUID。”		它接受名称、ID、UUID 或域名。