HTMLBox
Log in Create account
Help Center

API & CLI

API and CLI

The public API and HTMLBox CLI require active account Premium. Use scoped tokens to manage Boxes and deploy ZIPs, while Free browser publishing remains available.

Create and protect a token

Activate account Premium in Plans before creating a personal access token in the signed-in API & CLI dashboard area. Every API and CLI request requires active Premium, including requests using existing tokens.

Treat a token like a password. Store it in a secret manager or CI secret, never in source control, browser code, screenshots, or a public ZIP.

  1. Open API & CLI in the Dashboard.
  2. Create a token with only the access you need.
  3. Use it in an Authorization Bearer header or through the CLI login command.
  4. Revoke it from the Dashboard when it is no longer needed.

Premium access and renewal

Buying credit packs alone does not enable API or CLI access. Activate or renew account Premium through Account Plans.

If Premium expires, an existing token returns 403 premium_required. An unrevoked token becomes usable again after renewal. Token inspection and revocation remain available without Premium.

Losing API access does not itself suspend hosted sites or cancel already accepted imports. Free accounts can still publish and manage Free Boxes through the dashboard.

Use the CLI

The CLI accepts exactly one readable .zip file. It can list Boxes, start an asynchronous deployment, inspect an import, and optionally wait for the import to finish.

Tips and limits

  • For CI, set HTMLBOX_TOKEN in the CI secret store. It takes precedence over stored CLI credentials and is not written to the CLI config file.
  • Use --json for machine-readable CLI output.
  • Use --wait when an automation step needs the completed hosted URL before continuing.
htmlbox deploy ./site.zip --wait
HTMLBOX_TOKEN=... htmlbox boxes list --json

Know the boundaries

Tips and limits

  • If Premium expires or becomes inactive, requests return 403 premium_required. Renew in Account Plans to restore access. You can still inspect and revoke tokens, manage Free Boxes in the browser, and keep existing hosted sites online under their normal hosting policies.
  • The CLI does not accept directories, zip folders, watch or synchronize files, edit Live Workspace files, activate Releases, or make billing changes.
  • API ZIP imports accept one public ZIP URL or one multipart local ZIP. They are asynchronous and should be polled until a terminal status.
  • The API base URL is https://htmlbox.io/api/v1. Consult the API reference for endpoint payloads and error envelopes.

Related guides

Boxes

Create a Box

Deploy a static frontend from the Author Dashboard. The creation screen uses a deploy-first first stage, then opens operational controls after the first Release is ready.

Boxes

Deployments and Releases

A Release is an immutable record of one deployment. Updating a site creates another Release instead of overwriting a previous one.

Plans

Plans and billing

Boxes can be Community, Free, or Dedicated. Account Premium enables Dedicated capability, and flexible credits are pooled across the account.