@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.

The common route to launch oxygen-cli's deploy command locally is through hydrogen-cli. When this is installed globally, the command is available via the h2 deploy.

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.

Finally, it is also possible to install the oxygen-cli independently, which is preferable when run from within a CI/CD environment.

npm install -g @shopify/oxygen-cli

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

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).
• -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: yarn build).
• -h, --skipHealthCheck: Skip running the health check on the deployment
• -d, --healthCheckMaxDuration: The maximum duration (in seconds) that the health check is allowed to run before it is considered failed. Accepts values between 10 and 300.
• --publicDeployment: set the deployment to be publicly accessible.
• --metadataUrl : URL that links to the deployment.
• --metadataUser : User that initiated the deployment.
• --metadataVersion : A version identifier for the deployment.

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

Example:

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

This command will deploy your Oxygen project to the staging environment 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.

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	BITBUCKET_COMMIT_AUTHOR	CIRCLE_USERNAME	GITHUB_ACTOR	GITLAB_USER_LOGIN
Version	BITBUCKET_COMMIT	CIRCLE_SHA1	GITHUB_SHA	CI_COMMIT_SHA
URL	BITBUCKET_BUILD_URL	CIRCLE_BUILD_URL	${GITHUB_SERVER_URL}${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}	CI_PROJECT_URL

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

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).