Smooth Bundle – CLI Tool

Smooth Bundle CLI is a command-line tool for managing projects and assets on Smooth Bundle.

It helps you initialize projects, upload assets, optionally manage versions, and control access to protected resources.

The CLI uses a local configuration file (.sbundle.json) to define project settings, asset sources, and ignore patterns. If an existing .scdn.json file is found and .sbundle.json does not exist yet, the CLI copies it to .sbundle.json automatically and continues with the new file name.

For CI/CD, you can provide the SBUNDLE_TOKEN environment variable to authenticate the CLI in non-interactive environments.

Full documentation

Requirements

• Smooth Bundle account – create an account
• Node.js ≥ 18.17.0 (recommended: Node.js 20 LTS)

Installation

npm install -g @smoothbundle/cli

The primary command is sbundle. The package also exposes sbndl as a short alias for the same CLI.

Commands

sbundle login

Logs in to your Smooth Bundle account.

sbundle logout

Logs out from your Smooth Bundle account.

sbundle init

Initializes a new project and creates a local configuration file.

sbundle load

Loads an existing project into the local config file.

sbundle pull-config

Pulls the current Smooth Bundle user and project status into .sbundle.json.

sbundle push-config

Pushes project settings from .sbundle.json to Smooth Bundle.

This updates project name, slug, custom subdomain, bot blocking, headless browser blocking, and image variants. It does not publish or switch deployment versions; use sbundle version publish for that.

sbundle version add [version]

Creates a new version and sets it as the active deployment target.

If no version is provided, the version from the config file will be used.

Optionally add --blank to create blank version (without any assets from previous version).

sbundle version list

Lists versions for the current project, including publication status and the version currently selected in .sbundle.json.

sbundle version publish [version]

Publishes the selected version.

If no version is provided, the version from the config file will be published.

Publishing a version also points the system latest tag at that version.

sbundle version unpublish [version]

Unpublishes the selected version and removes it from delivery.

If no version is provided, the version from the config file will be unpublished.

If the system latest tag points at this version, update latest to another published version before relying on it.

sbundle version delete [version]

Permanently deletes the selected version and its assets.

If no version is provided, the version from the config file will be deleted.

sbundle tag list
sbundle tag set production 1.0.0
sbundle tag delete production

Lists, creates, repoints or deletes custom version tags for the current release project.

The system latest tag is always available for release projects. Use sbundle version publish to point latest at a published version.

sbundle push

Uploads assets to Smooth Bundle.

Use --concurrency <number> to set parallel upload workers (default: 4).

Use --optimize=remote to queue asset optimization on the Smooth Bundle side (default).

Local audio and video optimization require ffmpeg, and local PDF optimization requires Ghostscript (gs).

Use --optimize=local to optimize assets in the CLI before upload.

If you want to rewrite uploaded asset paths, add the replacePath field to .sbundle.json.

Example .sbundle.json:

{
  "replacePath": {
    "/dist/": "/",
    "/build/": "/assets/"
  }
}

For example, /dist/images/logo.png can be uploaded as /images/logo.png, and /build/app.js can be uploaded as /assets/app.js.

Image variants can be disabled or configured with one of the supported presets: basic or extended. When variants are enabled, the CLI writes the selected preset to .sbundle.json as the imageVariants string and automatically generates resized variants for images, linked to the original asset. Choosing None omits the imageVariants field. Custom breakpoint maps are not supported in the config file.

Example .sbundle.json:

{
  "imageVariants": "basic"
}

For original.png, this creates variants such as original_sm.png, original_lg.png and original_xl.png, but only when the source image is wider than the configured variant.

The extended preset creates xs 320, sm 640, md 960, lg 1280, xl 1600 and xxl 1920.

sbundle pull

Downloads remote assets that do not exist locally.

Generated or optimized formats such as WebP, AVIF, M4A, M4V or image breakpoint variants are restored into the local .sbundle cache, matching the cache structure used by sbundle push --optimize=local.

Protected assets are downloaded with the current Smooth Bundle bearer token, so the command also works for private CDN files when you are logged in or SBUNDLE_TOKEN is set.

sbundle prune

Cross-checks local assets against the ones on Smooth Bundle and removes remote assets that do not exist locally.

sbundle get-snippet

Outputs an embed snippet for the selected asset.

For images with configured imageVariants, the command can generate either a single-image snippet or a responsive <img> snippet with srcset.

sbundle check-assets

Validates asset paths and lists assets before deployment.

sbundle types

Generates smoothbundle-loader.ts for @smoothbundle/loader.

The generated file reads .sbundle.json, applies configured sources, excludes, protected, replacePath / replacePaths, and exposes TypeScript asset paths for loader components such as SmoothImage.

Use --output <path> to write the file somewhere else:

sbundle types --output src/smoothbundle-loader.ts

sbundle access list
sbundle access grant
sbundle access revoke

Lists, grants or revokes access tokens for protected assets.

sbundle collaborator list
sbundle collaborator add
sbundle collaborator remove

Lists, adds or removes project collaborators.

sbundle status
sbundle status --full

Displays account status, including current user, plan, and limits. Use --full to include project details.

Quick example

sbundle login
sbundle init
sbundle push