@byteplus/cdnsuite

BytePlus CDN suite CLI. This package currently ships the Node.js implementation for Pages static site hosting and Pages templates. The command name is cdnsuite.

The CLI is intentionally structured for later CDN, edge function, KV, cron, and other CDN suite modules. This release defaults to the BytePlus overseas production environment.

Requirements

• Node.js 20 or later
• A BytePlus access key pair with Pages permissions
• A project directory containing static assets, usually with an index.html

Install

npm install -g @byteplus/cdnsuite

For local project usage:

npm install --save-dev @byteplus/cdnsuite
npx cdnsuite --help

Login And Configuration

Configure AK/SK once globally:

cdnsuite config set -g cloud.access_key YOUR_ACCOUNT_ACCESS_KEY
cdnsuite config set -g cloud.secret_key YOUR_ACCOUNT_SECRET_KEY

View the effective config. Secrets are redacted by default:

cdnsuite config

The CLI reads cdnsuite config files by default:

• Global config: ~/.cdnsuite.json
• Project config: cdnsuite.json
• Custom config: cdnsuite -c ./cdnsuite.json ...

Older config files are read only as a migration fallback when the cdnsuite config files do not exist. New config writes use the cdnsuite file names.

Useful remotes:

cdnsuite pages list
cdnsuite --remote overseas pages list
cdnsuite --remote byteplus pages list

If --remote is omitted, cdnsuite uses BytePlus overseas production by default:

{
  "cloud": {
    "api_server": "https://cdn.byteplusapi.com",
    "api_region": "ap-singapore-1",
    "product": "CDN",
    "api_version": "2021-03-01"
  }
}

Quick Start

Create and publish a Pages project from a local static directory:

cdnsuite pages create --name demo-pages --upload ./site

The original manual also uses --assets and --deploy; both are accepted:

cdnsuite pages create --name demo-pages --assets ./site --deploy

Publishing usually takes a short while. Use get to check status and preview URL:

cdnsuite pages get -p p-xxxxxxxxxxxxxxxx

Pages Commands

Project

cdnsuite pages list
cdnsuite pages list --page 2
cdnsuite pages get -p p-xxxxxxxxxxxxxxxx
cdnsuite pages update -p p-xxxxxxxxxxxxxxxx --description "new description"
cdnsuite pages offline -p p-xxxxxxxxxxxxxxxx --yes
cdnsuite pages delete -p p-xxxxxxxxxxxxxxxx --yes

Project flags:

• --byteplus-project <project>
• --region <region> on pages create and pages update
• -Y, --yes skips confirmation for destructive commands

Deployment

cdnsuite pages deploy -p p-xxxxxxxxxxxxxxxx --upload ./site
cdnsuite pages list deployment -p p-xxxxxxxxxxxxxxxx

pages deploy requires the Pages project to be in a deployable state, usually online. If the project is still building, the server may reject the operation.

Domain

cdnsuite pages domain add -p p-xxxxxxxxxxxxxxxx --domain www.example.com
cdnsuite pages domain list -p p-xxxxxxxxxxxxxxxx
cdnsuite pages domain verify -p p-xxxxxxxxxxxxxxxx --domain www.example.com
cdnsuite pages domain delete -p p-xxxxxxxxxxxxxxxx --domain www.example.com --yes

After adding a custom domain, configure the required DNS CNAME record before relying on the domain in production.

Local Serve

cdnsuite pages serve --addr :8080 ./site

Pages Template Commands

cdnsuite template list
cdnsuite template get -t t-xxxxxxxxxxxxxxxx
cdnsuite template create ./site
cdnsuite template create ./site --online
cdnsuite template update -t t-xxxxxxxxxxxxxxxx ./site
cdnsuite template online -t t-xxxxxxxxxxxxxxxx --yes
cdnsuite template offline -t t-xxxxxxxxxxxxxxxx --yes
cdnsuite template delete -t t-xxxxxxxxxxxxxxxx --yes

Template APIs may not be available on every environment.

Pages Asset Limits

The CLI validates these limits before or during upload:

| Limit | Value | | --- | --- | | Compressed .tar.gz size | 50 MB | | File count in one asset directory | 500 | | Single file size | 25 MB |

Service-side limits from the manual:

| Limit | Value | | --- | --- | | Pages projects per account | 10 | | Historical assets per Pages project | 100 | | Monthly publishes per Pages project | 100 | | Custom domains per Pages project | 10 |

Error Handling

• Remote API errors include the action name, for example (ListPagesProject) InvalidAccessKey:....
• AK/SK are redacted from CLI config output and remote error messages.
• Non-JSON HTTP errors are surfaced as HTTP status errors instead of JSON decode failures.
• Upload commands always clean up temporary tarballs.

Verified Commands

The following command surfaces are covered by automated tests and package-shape verification:

• cdnsuite pages list
• cdnsuite pages create --upload
• cdnsuite pages create --assets --deploy
• cdnsuite pages get
• cdnsuite pages update
• cdnsuite pages deploy
• cdnsuite pages list deployment
• cdnsuite pages domain add/list/verify/delete
• cdnsuite pages offline
• cdnsuite pages delete
• cdnsuite pages serve
• cdnsuite template list

Development

npm install
npm run typecheck
npm test
npm run build

Verify the packaged command:

npm pack
npm install ./<tarball-from-npm-pack>.tgz
./node_modules/.bin/cdnsuite --help

Notes For Maintainers

• Package name: @byteplus/cdnsuite
• CLI command: cdnsuite
• Default config names are ~/.cdnsuite.json and cdnsuite.json