Skip to content

catalyst-cli-1.0.0.md

Latest commit

 

History

History
49 lines (41 loc) · 4.05 KB

catalyst-cli-1.0.0.md

File metadata and controls

49 lines (41 loc) · 4.05 KB
Raw
@bigcommerce/catalyst major

Introducing the Catalyst CLI (@bigcommerce/catalyst) — a single command-line tool for scaffolding, building, and deploying your Catalyst storefront to BigCommerce's Native Hosting infrastructure.

Highlights

  • Scaffold a storefront — catalyst create downloads a clean, standalone project (flattened from core/, workspace: dependencies resolved to published versions, fresh git repo) via tarball extraction and connects it to your BigCommerce store. The package manager is auto-detected from npm_config_user_agent.
  • Browser-based authentication — Run catalyst auth login to authenticate via an OAuth device code flow. Credentials are stored locally in .bigcommerce/project.json for use by all subsequent commands. CI/CD environments can use --store-hash and --access-token flags or environment variables instead.
  • Project & channel management — Create, link, and list BigCommerce infrastructure projects with catalyst project, and connect storefront channels with catalyst channel.
  • Build & deploy — catalyst build runs the OpenNext Cloudflare build pipeline (deriving the Wrangler compatibility_date dynamically) and generates deployment artifacts. catalyst deploy bundles, uploads, and deploys your storefront with real-time progress streaming. Pass runtime secrets with --secret KEY=VALUE; environment variables are auto-detected as deploy secrets.
  • Persisted deployment env vars — Manage deployment environment variables across deploys with catalyst env (list and remove; values are masked).
  • Custom domains — Add, list, check the status of, and remove custom domains for a Native Hosting project with catalyst domains.
  • Local preview — catalyst start launches a local Cloudflare Workers preview of your built storefront via the OpenNext adapter.
  • Live & historical logs — catalyst logs tail streams real-time application logs with color-coded levels and auto-reconnect; catalyst logs query retrieves historical logs.
  • In-place upgrades — catalyst upgrade upgrades a project to a newer version via a resilient 3-way merge (git merge-tree, falling back to per-file git merge-file), producing resolvable conflict markers instead of ever aborting.
  • Smart credential resolution — Configuration is resolved in priority order: CLI flags → --env-file → process environment variables → .bigcommerce/project.json.
  • Telemetry — Anonymous usage telemetry with session and correlation IDs for support. Opt out anytime with catalyst telemetry disable.

Commands

Command Description
catalyst create Scaffold and connect a Catalyst storefront to your BigCommerce store
catalyst auth Authenticate, sign out, and verify stored credentials
catalyst project Create, link, and list infrastructure projects
catalyst channel Connect a storefront channel to your project
catalyst build Build your Catalyst project for deployment
catalyst deploy Build and deploy to BigCommerce Native Hosting
catalyst env Manage persisted deployment environment variables
catalyst domains Manage custom domains for a Native Hosting project
catalyst start Start a local Cloudflare Workers preview
catalyst logs Stream live logs and query historical logs
catalyst upgrade Upgrade a project to a newer version via 3-way merge
catalyst version Display CLI, Node.js, and platform info
catalyst telemetry View or change telemetry collection status

Getting started

cd core
pnpm add @bigcommerce/catalyst@latest @opennextjs/cloudflare@1.17.3
pnpm catalyst auth login
pnpm catalyst project create
pnpm catalyst deploy --secret BIGCOMMERCE_STORE_HASH=<hash> --secret BIGCOMMERCE_STOREFRONT_TOKEN=<token>

For full documentation, see the Native Hosting Overview and CLI Reference.