@shopify/oxygen-cli

Oxygen-cli

@shopify/oxygen-cli is a command-line tool for deploying your Oxygen projects. It provides a simple a way to deploy your Oxygen applications, including workers and assets, to the Oxygen platform.

Getting Started

The oxygen-cli can be run locally, or it can be used from within CI/CD environments such as Github Actions.

Standalone

npm install -g @shopify/oxygen-cli

The CLI can then be activated using the command oxygen-cli.

As a Shopify Plugin

You can also install oxygen-cli as plugin for @shopify/cli. When this is installed globally, running the following will install oxygen-cli:

shopify plugins install @shopify/oxygen-cli

The CLI will now expose its commands under shopify oxygen.

Hydrogen

If you're building a Hydrogen storefront you'll want to use the hydrogen-cli wrapper. This package should automatically be included as a dependency in your application. This is a convenience wrapper around oxygen-cli to use nomenclature and design patterns that Hydrogen developers will be more familiar with.

Command overview

• oxygen deploy command initiates a deployment to Oxygen.

oxygen:deploy [options]

Options

• -t, --token: (required) Oxygen deployment token. Can also be set using the OXYGEN_DEPLOYMENT_TOKEN environment variable (see below).
• -p, --path: Root path (defaults to the current working directory).
• -e, --environmentTag: Tag of the environment to deploy to. Defaults to branch name in supported CI environments (see below).
• --defaultEnvironment: Deploys to the default environment of the app.
• -w, --workerFolder: Worker folder (default: dist/worker/).
• -a, --assetsFolder: Assets folder (default: dist/client/).
• -o, --workerOnly: Worker only deployment.
• -s, --skipBuild: Skip running build command.
• -b, --buildCommand: Build command (default: npm build).
• -v, --skipVerification: skip the worker deployment verification step
• -d, --verificationMaxDuration: The maximum duration (in seconds) that the deployment verification is allowed to run before it is considered failed. Accepts values between 10 and 300.
• --metadataDescription: A brief description of the deployment, typically the commit message associated with the changes being deployed.
• --metadataUrl: URL linking to the workflow/pipeline run in the CI platform from which the deployment is performed.
• --metadataUser: User that initiated the deployment.
• --metadataVersion: A version identifier for the deployment.
• --disableBugsnag: Disable Bugsnag error reporting.
• --generateAuthBypassToken: Generate an auth bypass token used to perform end-to-end testing against the deployment.
• --environmentFile: Path to an environment file to override existing environment variables for the deployment.

Note: All metadata options (--metadataDescription, --metadataUrl, --metadataUser, and --metadataVersion) have a maximum character limit of 375.

Example

oxygen:deploy -t my-deployment-token -e staging --path="/my-project" --workerOnly

This command will deploy your Oxygen project to the environment tagged staging with the provided deployment token and root path. No static assets will be uploaded.

The environmentTag option and the metadata options serve as overrides for values that can be retrieved from supported CI environments, see the section on environment variables below.

Deployment Verification

By default, oxygen-cli performs a verification step to ensure the worker deployment process has completed successfully. This step attempts to confirm the successful deployment of your worker. However, please note that this verification step does not dispatch requests to the worker, so it does not validate that the worker is correctly handling requests.

If you wish to skip this verification step, you can use the --skipVerification command flag.

The verification step runs for a default duration of 180 seconds. If the verification process does not complete successfully within this time, the deployment is considered unsuccessful. However, you can customize this duration using the --verificationMaxDuration command flag. This flag allows you to specify a maximum duration between 10 and 300 seconds for the verification process. If the verification process does not complete within your specified duration, the deployment will be considered unsuccessful.

In the case of the deployment verification failing, we recommend checking your Shopify Admin to confirm the status of the deployment.

Environment variables

The Oxygen deployment token can be specified with the token option. Alternatively, you can use the environment variable OXYGEN_DEPLOYMENT_TOKEN for this. In CI environments this is recommended. For example, when using CircleCI you can define a custom environment variable in your project settings which holds the token. The OXYGEN_DEPLOYMENT_TOKEN can then be populated with this variable's value in your config.yml file:

environment:
  OXYGEN_DEPLOYMENT_TOKEN: ${YOUR_ENV_VARIABLE}

When run from a supported CI/CD environment, the tool will automatically retrieve metadata from relevant environment variables. Metadata describes the author making the deployment (user), the version (commit Sha) and the deployment URL (workflow URL). This metadata will be saved and used to show details about the Oxygen deployment in the Hydrogen channel within the Shopify Admin.

The following environment variables are relevant, depending on your environment:

-	Bitbucket	CircleCI	Github	Gitlab
User	N/A	CIRCLE_USERNAME	GITHUB_ACTOR	GITLAB_USER_LOGIN
Version	BITBUCKET_COMMIT	CIRCLE_SHA1	GITHUB_SHA	CI_COMMIT_SHA
URL	https://bitbucket.org/${envs.BITBUCKET_WORKSPACE}/${envs.BITBUCKET_REPO_SLUG}/pipelines/results/${envs.BITBUCKET_BUILD_NUMBER}	CIRCLE_BUILD_URL	${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}	CI_PIPELINE_URL

These values can be overridden by the command line flags metadataUser, metadataUrl and metadataVersion respectively.

oxygen-cli Will also attempt to execute git log in your project folder to retrieve commit data. This allows the commit message and date to be saved and displayed in the Shopify Admin. If desired, the commit message can be overridden using the --metadataDescription command line flag.

The environment tag to deploy to will be derived from the following variables:

Service	Branch
Bitbucket	BITBUCKET_BRANCH
CircleCI	CIRCLE_BRANCH
Github	GITHUB_REF_NAME
Gitlab	CI_COMMIT_REF_NAME

The environmentTag command line option can be used to override this. If not provided, or there is no environment with the specified tag, the deployment will be deployed to the default environment for the app (if one exists).

Error reporting with Bugsnag

oxygen-cli Uses Bugsnag to collect errors that occur during the deployment process. This helps Shopify diagnose and fix issues more efficiently, improving the reliability of the tool. In addition, oxygen-cli collects anonymous usage data. This data is used to understand the performance of the tool and to improve its efficiency.

Bugsnag collects error reports which include stack traces, the type of error, and other relevant data that can help in diagnosing the issue. Please be aware that as part of the error reporting process, some user data related to your Continuous Integration (CI) environment may be logged. This data is used solely for the purpose of diagnosing and resolving issues.

Users who prefer not to send error reports can use the --disableBugsnag flag. When this flag is set, no error data will be sent to Bugsnag.