cloudcannon-sdk

The CloudCannon SDK

@cloudcannon/sdk is the REST API client the CloudCannon CLI is built on. It exposes a hierarchy of sub-clients over the API, plus a typed fetch that reaches endpoints no sub-client wraps.

Reach for it when the work is programmatic. Reach for the CLI when the work is a shell command.

When to use

• Calling the CloudCannon API from a script, a build step, or a service
• Operating over many sites or organisations in one pass
• Reaching a surface the CLI does not expose — DAMs, backups, sync history and pulls, site scans, screenshots, provider connect/disconnect, site.copy, site.delete
• Handling API failures by type rather than by exit code
• Finding out which methods exist, and what they take

When not to use

• A one-off operation from a shell — that is `cloudcannon-cli`. If a command already does the job, use it; it resolves site names, prints JSON, and needs no client wiring.
• Running the site locally in CloudCannon — cloudcannon dev is covered end to end by `cloudcannon-dev-server`. The SDK has nothing to do with it.
• Deciding what belongs in `cloudcannon.config.yml` — that is `cloudcannon-configuration`. The SDK reads and writes the file as bytes; it has no opinion on its contents.
• Authoring editable regions or snippets — `cloudcannon-visual-editing` and `cloudcannon-snippets`.

The rule that costs the most

MUST confirm with the user before any call that writes to a hosted site. This is the same rule the CLI carries, and the reason is the same — see `cloudcannon-cli` § The rule that costs the most for the canonical statement.

Two things make it easier to break here than at the command line:

• There is no command name to read as a warning. site.delete() is a method call with no arguments, no flag, and no confirmation prompt.
• The SDK reaches destructive endpoints the CLI has no command for at all — site.delete(), site.copy(), disconnectSourceProvider(), disconnectOutputProvider().

The gate covers `client.fetch` too. A POST through the escape hatch is a write.

Requirements

Node 20 or newer, per the package's engines field — lower than the CLI's Node 24. The package is ESM ("type": "module") and its default export is the client class.

import CloudCannonClient from "@cloudcannon/sdk";

Quick start

Sub-clients take a UUID and nothing else, so almost every task starts by finding one.

import CloudCannonClient from "@cloudcannon/sdk";

// The SDK reads no credentials of its own — you supply them.
const client = new CloudCannonClient({
  userAccessKey: {
    id: process.env.CC_ACCESS_KEY_ID,
    secret: process.env.CC_ACCESS_KEY_SECRET,
  },
});

const { items: orgs } = await client.orgs();
const { items: sites } = await client.org(orgs[0].uuid).sites({ filters: { search: "my-site" } });

const site = await client.site(sites[0].uuid).get();

Contents

Common mistakes