> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # Catalyst CLI > Reference for every Catalyst CLI command and flag, including create, deploy, env, logs, projects, channels, domains, auth, and upgrade. This page documents every Catalyst CLI command and its parameters. The CLI requires Node.js `22` or `24`. To understand what the CLI is for and how its configuration variables work, see the Native Hosting [Overview](/developer/docs/storefront/catalyst/deployment/native-hosting/overview). > **Warning** > > The Catalyst CLI is generally available, but Native Hosting is currently in > closed beta. There may be breaking changes to the Native Hosting APIs as we > finalize them. To express interest in gaining access, fill out the [Native Hosting Closed Beta Interest Form](https://docs.google.com/forms/d/e/1FAIpQLSfDepq3qRtEtavb1wQvSvdK21pwr_kNsYQbH2B7JjWYyptUSA/viewform?usp=header). 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 ```shell 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. > **Info** > > You won't typically run `catalyst create` directly, since `pnpm catalyst create` only works where the CLI is already installed. To scaffold a new project from scratch, run `pnpm create @bigcommerce/catalyst@latest` instead (see [CLI Installation](/developer/docs/storefront/catalyst/getting-started/cli-installation)). It runs `catalyst create` for you and passes through the same flags documented below. ### Parameters | Parameter | Required | Description | | :--------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--project-name ` | No | Name of your Catalyst project. Used as the directory name and display name. | | `--project-dir ` | No | Directory in which to create the project. Defaults to the current working directory. | | `--store-hash ` | No | The BigCommerce store hash (found in the URL of your store's Control Panel). Can also be set via `CATALYST_STORE_HASH`. | | `--access-token ` | No | Your BigCommerce access token. Can also be set via `CATALYST_ACCESS_TOKEN`. | | `--channel-id ` | No | BigCommerce channel ID to connect the storefront to. | | `--storefront-token ` | No | BigCommerce Storefront API token. | | `--hosting ` | No | Hosting mode: `self-hosted` or `commerce`. Use `commerce` to set up the project for Native Hosting at create time. When omitted, the project is scaffolded without hosting-specific setup, and `catalyst deploy` offers to set up Native Hosting later. | | `--use-existing` | No | When used with `--hosting commerce` and `--project-name`, reuses an existing infrastructure project instead of prompting to create one. | | `--gh-ref ` | No | Extract a specific Git ref (tag, branch, or commit) from the source repository. Defaults to `@bigcommerce/catalyst-core@latest`. | | `--repository ` | No | GitHub repository to extract from. Defaults to `bigcommerce/catalyst`. | | `--env ` | No | Set an arbitrary environment variable in `.env.local`. Can be repeated to set multiple variables. | > **Info** > > The default `--gh-ref` (`@bigcommerce/catalyst-core@latest`) does not include Makeswift. Pass `--gh-ref @bigcommerce/catalyst-makeswift@latest` for a Makeswift-connected project. See [Makeswift](/developer/docs/storefront/catalyst/makeswift/overview). ### Example ```shell # Interactive setup (prompts for all required values) pnpm create @bigcommerce/catalyst@latest ``` ```shell # Self-hosted setup with explicit credentials pnpm create @bigcommerce/catalyst@latest --project-name my-store --store-hash --access-token ``` ```shell # Native Hosting setup pnpm create @bigcommerce/catalyst@latest --project-name my-store --hosting commerce --store-hash --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. **Passing credentials as flags.** If you pass both `--store-hash` and `--access-token` on the command line, the CLI logs in with them instead of opening the browser: it verifies them against your store and saves them to `.bigcommerce/project.json`, replacing any stored credentials. * If BigCommerce rejects them, the command exits with an error and nothing is saved. * If they can't be verified (for example, the API is unreachable), the CLI warns and saves them anyway. Values that come only from the `CATALYST_STORE_HASH` and `CATALYST_ACCESS_TOKEN` environment variables don't trigger this; the CLI treats them as already-resolved credentials, described next. **When credentials are already stored.** If a store hash and access token are already resolved, from environment variables or from a previous login, the CLI checks them first: * **Still valid:** it shows the store you're logged in to and exits. Run `catalyst auth logout` first, or pass `--force`, to log in again. * **Expired or revoked:** it warns and starts the login flow to re-authenticate. * **Can't be verified** (for example, the API is unreachable): it keeps them and exits. Re-run once the API is reachable, or pass `--force`. ### Parameters | Parameter | Required | Description | | :----------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--store-hash ` | No | The BigCommerce store hash. When passed along with `--access-token`, the CLI verifies and stores those credentials instead of running the browser login flow. Can also be set via `CATALYST_STORE_HASH`. | | `--access-token ` | No | Your BigCommerce access token. When passed along with `--store-hash`, the CLI verifies and stores those credentials instead of running the browser login flow. Can also be set via `CATALYST_ACCESS_TOKEN`. | | `--force` | No | Skip the check on already-stored credentials and re-authenticate regardless. When combined with `--store-hash` and `--access-token`, stores those credentials without verifying them. | ### Example ```shell # Login via browser (recommended) pnpm catalyst auth login ``` ```shell # Log in with existing credentials (verifies and stores them) pnpm catalyst auth login --store-hash --access-token ``` ```shell # Re-authenticate even if credentials are already stored pnpm catalyst auth login --force ``` --- ## auth logout Remove stored credentials for the current project. ### Parameters This command does not accept any parameters. ### Example ```shell pnpm catalyst auth logout ``` --- ## auth whoami Verify your stored credentials and display information about the authenticated store and linked project. ### Parameters | Parameter | Required | Description | | :----------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--store-hash ` | No | The BigCommerce store hash (found in the URL of your store's Control Panel). Can also be set via the `CATALYST_STORE_HASH` environment variable or `.bigcommerce/project.json`. | | `--access-token ` | No | Your BigCommerce access token. Can also be set via the `CATALYST_ACCESS_TOKEN` environment variable or `.bigcommerce/project.json`. | ### Example ```shell pnpm catalyst auth whoami ``` Example output: ```text showLineNumbers={false} 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 ```shell 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 | Parameter | Required | Description | | :----------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--project-uuid ` | No | The UUID of the project to include in the deployment configuration. Required for Native Hosting builds but can also be set via `CATALYST_PROJECT_UUID` or the `.bigcommerce/project.json` file. | | `--wrangler-version ` | No | The Wrangler version or dist-tag to build with. When omitted, the CLI's pinned default is used (`4.128.0` as of CLI 1.4.2). Must look like a version or dist-tag (for example, `4.128.0` or `latest`). | | `--env-path ` | No | Path to an environment file to load for the build (resolved relative to the current working directory). When omitted, `.env.local` and `.env` are auto-loaded from the current directory instead (`.env.local` takes precedence, and neither overrides variables already set in your shell). If the file does not exist or cannot be parsed, the command exits with an error. Env files supply storefront build variables only — the CLI's own `CATALYST_*` credentials are never read from them. | ### Example ```shell pnpm catalyst build ``` ```shell # Build with a specific Wrangler version pnpm catalyst build --wrangler-version latest ``` ```shell # 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. If the linked project no longer exists on the store (for example, it was deleted), the CLI warns and prompts you to select or create another one. If the project isn't set up for Native Hosting yet, `deploy` asks whether to run Commerce Hosting setup now (default Yes). Accepting transforms the project for Native Hosting and reinstalls dependencies before continuing; declining exits without deploying. See [Set up with an existing project](/developer/docs/storefront/catalyst/deployment/native-hosting/getting-started#set-up-with-an-existing-project) for what setup changes. Runtime secrets can be persisted with [`env add`](#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. Without `--update-site-url` or `--update-checkout-url`, an interactive deploy offers to point the storefront's channel (its `BIGCOMMERCE_CHANNEL_ID`) at the deployment, and to move its checkout onto the storefront's domain. Both offers default to No, and declining either is saved for that channel in `.bigcommerce/project.json`. Nothing is offered when the terminal isn't interactive or `CI` is set. See [Checkout domains](/developer/docs/storefront/catalyst/deployment/native-hosting/checkout-domains#set-it-during-a-deploy). ### Parameters | Parameter | Required | Description | | :----------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--store-hash ` | No | The BigCommerce store hash (found in the URL of your store's Control Panel). Can also be set via the `CATALYST_STORE_HASH` environment variable or `.bigcommerce/project.json`. | | `--access-token ` | No | Your BigCommerce access token. Can also be set via the `CATALYST_ACCESS_TOKEN` environment variable or `.bigcommerce/project.json`. | | `--project-uuid ` | No | The UUID of the project to deploy to. Can also be set via the `CATALYST_PROJECT_UUID` environment variable or `.bigcommerce/project.json`. | | `--secret ` | No | A runtime secret for this deployment. Can be passed multiple times. Overrides any value stored for the same key with `catalyst env add`. Supply all required runtime secrets either with `--secret`, with `catalyst env add`, or as environment variables. | | `--prebuilt` | No | Skips the build step. Requires `.bigcommerce/dist/` to already contain build output. | | `--update-site-url` | No | After a successful deploy, prompt to update a channel's site URL to the new deployment hostname. See [`channels update`](#channels-update). | | `--update-checkout-url` | No | After a successful deploy, update a channel's checkout URL. On an auto-generated hostname it sets the storefront's `c.` checkout hostname and waits for its certificate; on a custom domain it prompts for the URL. Passing this together with `--update-site-url` asks which channel only once. | | `--dry-run` | No | Generate the bundle without uploading or deploying. | | `--wrangler-version ` | No | The Wrangler version or dist-tag to build with. Ignored when `--prebuilt` is passed, since no build runs. When omitted, the CLI's pinned default is used (`4.128.0` as of CLI 1.4.2). Must look like a version or dist-tag (for example, `4.128.0` or `latest`). | | `--env-path ` | No | Path to an environment file to load for the build (resolved relative to the current working directory). Ignored when `--prebuilt` is passed, since no build runs. When omitted, `.env.local` and `.env` are auto-loaded from the current directory instead (`.env.local` takes precedence, and neither overrides variables already set in your shell). If the file does not exist or cannot be parsed, the command exits with an error. Env files supply storefront build variables only — the CLI's own `CATALYST_*` credentials are never read from them. | ### Example ```shell pnpm catalyst deploy --secret BIGCOMMERCE_STORE_HASH= --secret BIGCOMMERCE_STOREFRONT_TOKEN= ``` ```shell # 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 | Parameter | Required | Description | | :---------- | :------- | :------------------------------------------------------- | | `` | Yes | One or more environment variables in `KEY=VALUE` format. | ### Example ```shell pnpm catalyst env add BIGCOMMERCE_STORE_HASH= BIGCOMMERCE_STOREFRONT_TOKEN= ``` --- ## env remove Remove one or more stored deployment environment variables. ### Parameters | Parameter | Required | Description | | :---------- | :------- | :------------------------------------------------ | | `` | Yes | One or more environment variable names to remove. | ### Example ```shell 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 ```shell 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. `tail` is the default `logs` subcommand, so `pnpm catalyst logs` on its own runs `pnpm catalyst logs tail`. ### Parameters | Parameter | Required | Description | | :----------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--store-hash ` | No | The BigCommerce store hash (found in the URL of your store's Control Panel). Can also be set via the `CATALYST_STORE_HASH` environment variable or `.bigcommerce/project.json`. | | `--access-token ` | No | Your BigCommerce access token. Can also be set via the `CATALYST_ACCESS_TOKEN` environment variable or `.bigcommerce/project.json`. | | `--project-uuid ` | No | The project UUID. Can also be set via an environment variable named `CATALYST_PROJECT_UUID` or the `.bigcommerce/project.json` file. | | `--format ` | No | Output format for log events. Choices: `json`, `pretty`, `default`, `short`, `request`. Defaults to `default`. | The available formats are: * `default` — `[timestamp] [LEVEL] message` * `short` — message only * `request` — `[timestamp] METHOD URL (status_code) [LEVEL] message`. Requests that logged no messages are printed too, without the level and message. * `json` — raw JSON, one event per line * `pretty` — indented JSON of the whole event The `default` and `short` formats only print requests that produced a log message. Use `request`, `json`, or `pretty` to see every request. ### Example ```shell pnpm catalyst logs tail ``` ```shell # Tail logs with request format pnpm catalyst logs tail --format request ``` ```shell # 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 | Parameter | Required | Description | | :----------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--store-hash ` | No | The BigCommerce store hash (found in the URL of your store's Control Panel). Can also be set via the `CATALYST_STORE_HASH` environment variable or `.bigcommerce/project.json`. | | `--access-token ` | No | Your BigCommerce access token. Can also be set via the `CATALYST_ACCESS_TOKEN` environment variable or `.bigcommerce/project.json`. | | `--project-uuid ` | No | The project UUID. Can also be set via an environment variable named `CATALYST_PROJECT_UUID` or the `.bigcommerce/project.json` file. | | `--since ` | No | Relative window ending at `--end` (default: now), for example `30m`, `6h`, or `2d` (units: `s`, `m`, `h`, `d`). Cannot be combined with `--start`. | | `--start