Catalyst CLI

Make sure to read the Overview documentation to understand the purpose of the CLI, how configuration variables work, etc. The Catalyst CLI supports the following commands:

Configuration values are resolved in this priority order: flags > environment variables > .bigcommerce/project.json. If CATALYST_STORE_HASH is unset, the CLI falls back to BIGCOMMERCE_STORE_HASH.

Commands that manage a resource are named in the plural — projects, channels, domains, and logs. Each one also accepts its singular form as an alias, so catalyst project list and catalyst projects list do the same thing. The plural form is canonical; use it in new scripts.

version

Display detailed version information (CLI version, Node version, and platform).

Parameters

This command does not accept any parameters.

Example

$
pnpm catalyst version

create

Scaffold a new Catalyst storefront and connect it to your BigCommerce store. The CLI will prompt for any required values not passed as flags.

Parameters

Example

$
# Interactive setup (prompts for all required values)
$
pnpm catalyst create

$
# Self-hosted setup with explicit credentials
$
pnpm catalyst create --project-name my-store --store-hash <STORE_HASH> --access-token <ACCESS_TOKEN>

$
# Native Hosting setup
$
pnpm catalyst create --project-name my-store --hosting commerce --store-hash <STORE_HASH> --access-token <ACCESS_TOKEN>

auth login

Authenticate with BigCommerce via your browser. Uses an OAuth device code flow. The CLI displays a one-time code, opens your browser to the BigCommerce login page, and waits for you to authorize. After logging in, your credentials are stored in .bigcommerce/project.json. Falls back to an interactive store hash + access token prompt if the browser flow is unavailable.

If a store hash and access token are already resolved — from --store-hash/--access-token, or already stored from a previous login — the CLI doesn’t attempt to log in again: it displays those credentials and suggests running catalyst auth logout first to re-authenticate.

Parameters

Example

$
# Login via browser (recommended)
$
pnpm catalyst auth login

$
# Check already-logged-in status without re-authenticating
$
pnpm catalyst auth login --store-hash <STORE_HASH> --access-token <ACCESS_TOKEN>

auth logout

Remove stored credentials for the current project.

Parameters

This command does not accept any parameters.

Example

$
pnpm catalyst auth logout

auth whoami

Verify your stored credentials and display information about the authenticated store and linked project.

Parameters

Example

$
pnpm catalyst auth whoami

Example output:

Logged in to My Store (abc123), connected to project my-project (43eba682-0c48-11f1-9bd5-827a48b0ce1e)

If no credentials are found, the command exits with a “not logged in” message.

start

Start a local preview of your Catalyst storefront. For projects set up for Commerce Hosting, this previews the OpenNext/Cloudflare build via Wrangler and requires a successful catalyst build first. For self-hosted projects, it falls back to next start instead.

Before the Commerce Hosting preview, the CLI symlinks .bigcommerce/.dev.vars to your .env.local (so Wrangler picks up the same variables) unless .dev.vars already exists as something else, in which case it warns and leaves it alone. If .env.local doesn’t exist, it warns that the preview may fail without environment variables.

Parameters

This command does not accept any parameters.

Example

$
pnpm catalyst start

build

Build your Catalyst project. If the project is configured for Native Hosting (Commerce Hosting), this runs the OpenNext/Cloudflare pipeline and a Wrangler dry-run to generate deployment artifacts. Otherwise, it falls back to next build.

Parameters

Example

$
pnpm catalyst build

$
# Build with a specific Wrangler version
$
pnpm catalyst build --wrangler-version 4.24.3

$
# Build using an explicit env file instead of the auto-loaded .env.local/.env
$
pnpm catalyst build --env-path .env.prod

deploy

Deploy your application to Cloudflare. By default, this also runs a build before deploying which can be skipped with the --prebuilt flag. Generates a bundle from .bigcommerce/dist, uploads it to BigCommerce, and creates a deployment. If no project is linked and --project-uuid isn’t passed, the CLI prompts you to select or create one and links it automatically before continuing.

Runtime secrets can be persisted with env add — they are sent automatically on every deploy — or passed per run with --secret. A --secret value overrides any stored value for the same key.

Parameters

Example

$
pnpm catalyst deploy --secret BIGCOMMERCE_STORE_HASH=<YOUR_STORE_HASH> --secret BIGCOMMERCE_STOREFRONT_TOKEN=<YOUR_STOREFRONT_TOKEN>

$
# Deploy using an explicit env file instead of the auto-loaded .env.local/.env
$
pnpm catalyst deploy --env-path .env.prod

env add

Add or update one or more deployment environment variables. Stored in .bigcommerce/project.json and sent as secrets on every catalyst deploy, so you no longer need to pass --secret for each one. Run a value through --secret on deploy only when you want to override a stored value for a single run.

Parameters

Example

$
pnpm catalyst env add BIGCOMMERCE_STORE_HASH=<YOUR_STORE_HASH> BIGCOMMERCE_STOREFRONT_TOKEN=<YOUR_STOREFRONT_TOKEN>

env remove

Remove one or more stored deployment environment variables.

Parameters

Example

$
pnpm catalyst env remove BIGCOMMERCE_STOREFRONT_TOKEN

env list

List stored deployment environment variables. Values are masked.

Parameters

This command does not accept any parameters.

Example

$
pnpm catalyst env list

logs tail

Tail live logs from your deployed application. Streams log output in real time using Server-Sent Events (SSE). The stream automatically reconnects on transient errors (up to 5 retries). Authentication errors (401) and other 4xx responses are treated as fatal instead — the command exits immediately rather than retrying, since reconnecting won’t resolve them.

Parameters

The available formats are:

• default — [timestamp] [LEVEL] message
• short — message only
• request — [timestamp] [LEVEL] METHOD URL (status_code) message
• json — raw JSON output
• pretty — pretty-printed JSON

Example

$
pnpm catalyst logs tail

$
# Tail logs with request format
$
pnpm catalyst logs tail --format request

$
# Tail logs as raw JSON (useful for piping to other tools)
$
pnpm catalyst logs tail --format json

logs query

Query historical logs from your deployed application. Specify a time window with --since (relative to now) or with --start/--end (absolute timestamps), and optionally filter by HTTP method, status code, URL, and log level. The window may not exceed 7 days. Entries print oldest-first, with timestamps in UTC.

Parameters

The available formats are the same as logs tail.

Example

$
# Last hour of logs
$
pnpm catalyst logs query --since 1h

$
# Newest 20 errors in the window (follow the printed --after hint for more)
$
pnpm catalyst logs query --since 24h --level-min error --limit 20

$
# Everything from a given start time (UTC)
$
pnpm catalyst logs query --start 2026-06-11T00:00:00Z

$
# Errors only for a specific path
$
pnpm catalyst logs query --since 24h --level-min error --url-like /cart

$
# Errors with request details (method, URL, status)
$
pnpm catalyst logs query --since 1h --level-min error --format request

$
# Raw JSON (NDJSON) for piping to other tools
$
pnpm catalyst logs query --since 2d --format json

projects create

Create a new BigCommerce infrastructure project and link it to your local Catalyst project. The project UUID is written to .bigcommerce/project.json. Walks you through logging in via the browser device-code flow (the same flow as auth login) if you aren’t authenticated yet.

Parameters

Example

$
# Create a project (prompts for project name)
$
pnpm catalyst projects create

$
# Create a project and pass store hash and access token
$
pnpm catalyst projects create --store-hash <STORE_HASH> --access-token <ACCESS_TOKEN>

projects link

Link your local Catalyst project to a BigCommerce infrastructure project. You can provide a project UUID directly, or use store credentials to fetch and select from available projects (or create a new one). The linked project UUID is written to .bigcommerce/project.json.

After linking, if the project isn’t already set up for Commerce Hosting, the CLI asks whether to run that setup now (transforming the project and installing dependencies). If the project is already set up, this step is skipped, though the CLI still silently cleans up any Cloudflare-incompatible artifacts left over from before.

Parameters

Example

$
# Link using a project UUID directly
$
pnpm catalyst projects link --project-uuid <UUID>

$
# Link by fetching projects (prompts to select or create)
$
pnpm catalyst projects link --store-hash <STORE_HASH> --access-token <ACCESS_TOKEN>

projects list

List BigCommerce infrastructure projects for your store. The currently linked project is highlighted.

Parameters

Example

$
pnpm catalyst projects list

$
# List projects by passing store hash and access token
$
pnpm catalyst projects list --store-hash <STORE_HASH> --access-token <ACCESS_TOKEN>

projects delete

Permanently delete a BigCommerce infrastructure project. This action is irreversible. If --project-uuid is not provided, the CLI fetches available projects and prompts you to select one. A confirmation prompt is shown before deletion unless --force is passed.

Parameters

Example

$
# Delete a project (prompts for selection and confirmation)
$
pnpm catalyst projects delete

$
# Delete a specific project by UUID
$
pnpm catalyst projects delete --project-uuid <UUID>

$
# Delete without confirmation prompt
$
pnpm catalyst projects delete --project-uuid <UUID> --force

channels create

Create a new Catalyst storefront channel on your BigCommerce store. This is the same channel-creation flow offered by create during scaffolding, exposed as a standalone command so you can add channels to an existing project without scaffolding a new one.

Like channels link, this is an onboarding command: if you are not already authenticated, it logs you in via the browser device-code flow (the same flow as auth login) before continuing. It then checks whether your store is eligible to create a Catalyst channel and exits with the store’s message if it is not.

By default it prompts for the channel name, a default language, optional additional languages (up to 4), and whether to install sample data. Pass the corresponding flags to skip any prompt. Passing more than 4 values to --additional-locales fails immediately with an error, before any network call.

After the channel is created, the CLI asks whether to link it to your project — writing the channel’s credentials (store hash, storefront token, channel ID, etc.) to .env.local in the current working directory, the same as channels link. Pass --link to write the credentials without prompting.

Parameters

Example

$
# Create a channel interactively (logs you in if needed)
$
pnpm catalyst channels create

$
# Create a channel non-interactively and link it to this project
$
pnpm catalyst channels create --name "My Store" --locale en --no-sample-data --link

$
# Add additional storefront languages
$
pnpm catalyst channels create --name "My Store" --additional-locales es fr

channels link

Link this Catalyst project to a BigCommerce channel and write its credentials to .env.local. This is an onboarding command: if you are not already authenticated, it logs you in via the browser device-code flow (the same flow as auth login) before continuing. By default it prompts you to pick from the storefront channels on your store; pass --channel-id to skip the picker.

The channel’s environment variables (store hash, storefront token, channel ID, etc.) are written to .env.local in the current working directory — run this from inside your project’s core/ directory, the same place you run dev, build, and deploy.

Parameters

Example

$
# Pick a channel interactively (logs you in if needed)
$
pnpm catalyst channels link

$
# Link a specific channel non-interactively
$
pnpm catalyst channels link --store-hash <STORE_HASH> --access-token <ACCESS_TOKEN> --channel-id 123

$
# Append extra environment variables to .env.local
$
pnpm catalyst channels link --channel-id 123 --env MY_FLAG=1

channels update

Update a BigCommerce channel’s site URL to point at one of your project’s deployment hostnames. Runs interactively by default, prompting you to select a channel and a hostname. Pass --channel-id and --hostname to skip the prompts. Run projects list to see the available deployment hostnames. If no project is linked, the CLI prints guidance to run projects create instead of failing.

Parameters

Example

$
# Pick a channel and hostname interactively
$
pnpm catalyst channels update

$
# Skip both prompts
$
pnpm catalyst channels update --channel-id 123 --hostname my-storefront.example.com

domains add

Add a custom domain to the current Native Hosting project. Newly added domains start in a pending verification state; pass --wait to poll until verification completes or times out (5 minutes).

Parameters

Example

$
pnpm catalyst domains add www.example.com

$
# Wait until the domain leaves pending verification
$
pnpm catalyst domains add www.example.com --wait

domains list

List custom domains for the current Native Hosting project, along with each domain’s verification status.

Parameters

Example

$
pnpm catalyst domains list

$
# Show pending domains only
$
pnpm catalyst domains list --status pending

domains status

Show the verification status of a custom domain on the current Native Hosting project. Pass --wait to poll until a pending domain finishes verifying.

Parameters

Example

$
pnpm catalyst domains status www.example.com

$
# Wait until the domain leaves pending verification
$
pnpm catalyst domains status www.example.com --wait

domains claim

Claim ownership of a custom domain that is currently in use on another store. When you try to add a domain that is already bound to a different store, catalyst domains add prints an ownership-verification TXT record. Publish that record with your DNS provider, then run this command to release the domain from the other store and bind it to your project. If ownership has not yet been verified, the command prints the TXT record again so you can publish it and retry. Pass --wait to poll until the claimed domain finishes verifying.

Parameters

Example

$
pnpm catalyst domains claim www.example.com

$
# Wait until the claimed domain leaves pending verification
$
pnpm catalyst domains claim www.example.com --wait

domains transfer

Transfer a custom domain from its current project to another project in the same store. This is the same-store counterpart to catalyst domains claim (which handles domains in use on a different store): when you try to add a domain already bound to another project in your store, catalyst domains add tells you to transfer it. The source is the current (linked) project; the destination is the project you transfer to. Omit --to-project-uuid to pick the destination interactively from your store’s projects. Pass --wait to poll until the transferred domain finishes verifying.

If the domain isn’t found on the current (linked) project, the CLI scans the store’s other projects to find which one actually owns it, then prints the exact domains transfer command to re-run from there — it won’t guess and transfer from the wrong project.

Parameters

Example

$
# Pick the destination project interactively
$
pnpm catalyst domains transfer www.example.com

$
# Transfer to a specific project
$
pnpm catalyst domains transfer www.example.com --to-project-uuid <PROJECT_UUID>

domains remove

Remove a custom domain from the current Native Hosting project. If the domain is active (verified), the CLI prompts for confirmation before removing it, since traffic may stop routing to the project. Pass --force to skip the prompt.

Parameters

Example

$
pnpm catalyst domains remove www.example.com

$
# Skip confirmation for an active domain
$
pnpm catalyst domains remove www.example.com --force

upgrade

Upgrade your Catalyst project to a newer version by applying a 3-way merge between your project’s base version, your local changes, and the target version. Conflicts are written as standard <<<ours/===/theirs>>> markers — the upgrade never aborts. Run this from inside a Catalyst git repository with a clean working tree (commit or stash local changes first).

Catalyst versions are git tags on the bigcommerce/catalyst repository, not npm packages. Set the GITHUB_TOKEN environment variable to raise the GitHub API rate limit. The command has the aliases up.

If your project’s package.json has no catalyst.ref field and --from isn’t passed, the CLI infers a base version from the package name and version, asks you to confirm it (unless --yes is passed), and — after downloading — warns if the inferred base looks unreliable (less than 50% of its files match your project), suggesting you re-run with --from <correct-version>.

Parameters

Example

$
# Upgrade to the latest Catalyst version
$
pnpm catalyst upgrade

$
# Upgrade to a specific version
$
pnpm catalyst upgrade 1.8.0

$
# Preview what would change without applying
$
pnpm catalyst upgrade --dry-run

$
# Upgrade to an integration family (makeswift, b2b-makeswift, ...)
$
pnpm catalyst upgrade --ref @bigcommerce/catalyst-makeswift@1.7.0

telemetry

View or change CLI telemetry collection status (enable, disable, or show current status). Enabling telemetry helps BigCommerce support diagnose and troubleshoot errors.

Parameters

Example

$
# Show telemetry status
$
pnpm catalyst telemetry

$
# Enable telemetry collection
$
pnpm catalyst telemetry enable

$
# Disable telemetry collection
$
pnpm catalyst telemetry --disable

debug

Print a diagnostic report — CLI version, runtime, project state, resolved config, telemetry status, and the presence of key project files — to include when filing a bug report. Credentials, stored environment variables, and CLI/build environment variables are always reported by presence and source only; secret values are never printed.

Parameters

Example

$
# Human-readable report
$
pnpm catalyst debug

$
# Machine-readable JSON
$
pnpm catalyst debug --json