SubQuery CLI

Most customers use the @subql/cli to just initialise, build, and run their projects locally, however the CLI can be used to do a whole lot more!

You can use the CLI to do the following:

• Create a new project on the SubQuery Managed Service
• Deploy a new version of your SubQuery project to the Managed Service
• Promote a staging deployment to the production slot in the SubQuery Managed Service
• and more! Type subql help to read the docs

This document may be outdated

The commands and parameters shown here may change, we suggest reviewing the current command and parameter list by using the --help command with your CLI

Installation

Install SubQuery CLI globally on your terminal by using Yarn or NPM:

npm

npm install -g @subql/cli

yarn

yarn global add @subql/cli

You can then run help to see available commands and usage provided by CLI:

subql help

Prepare your SUBQL_ACCESS_TOKEN

• Step 1: Go to SubQuery Managed Service and log in.
• Step 2: Click on your profile at the top right of the navigation menu, then click on Refresh Token.
• Step 3: Copy the generated token.
• Step 4: To use this token:
  • Option 1: Add SUBQL_ACCESS_TOKEN in your environment variables. EXPORT SUBQL_ACCESS_TOKEN=<token> (Windows) or export SUBQL_ACCESS_TOKEN=<token> (Mac/Linux)
  • Option 2: Coming soon, subql/cli will support storing your SUBQL_ACCESS_TOKEN locally.

Usage in GitHub Actions

With the introduction of the deployment feature for the CLI, we've added a Default Action Workflow to the starter project in GitHub that will allow you to publish and deploy your changes automatically:

Please review the documentation on how to deploy a new version of your project using GitHub actions.

Create a New Project

The CLI allows you to create a brand new project in the SubQuery Managed Service. It supports both interactive and non-interactive methods.

// Creating a project using the interactive method of the CLI
$ subql project:create-project

// OR using non-interactive method of the CLI, it will prompt you if the required fields are missing
$ subql project:create-project
    --apiVersion=apiVersion    [default: 2] Enter api version
    --description=description  Enter description
    --gitRepo=gitRepo          Enter git repository
    --logoURL=logoURL          Enter logo URL
    --org=org                  Enter organization name
    --projectName=projectName  Enter project name
    --subtitle=subtitle        Enter subtitle

Deploy a New Version of your Project

Using the CLI, you can deploy a new version of your SubQuery project to the Managed Service. It supports both interactive and non-interactive methods. You may want to run this command after you delete the target deployment slot (staging or primary).

Note

We suggest using the --useDefaults command for best results.

// Deploy using the interactive method of the CLI
$ subql deployment:deploy

// OR using non-interactive method of the CLI, it will prompt you if the required fields are missing
$ subql deployment:deploy
  -d, --useDefaults                Use default values for indexerVersion, queryVersion, dictionary, endpoint
  --dict=dict                      Enter dictionary
  --endpoint=endpoint              Enter endpoint
  --indexerVersion=indexerVersion  Enter indexer-version
  --ipfsCID=ipfsCID                Enter IPFS CID
  --org=org                        Enter organization name
  --projectName=projectName        Enter project name
  --queryVersion=queryVersion      Enter query-version
  --type=(stage|primary)           [default: primary]

Promote a Staging Deployment to Production Slot

This command will promote a staging deployment to the production slot in the SubQuery Managed Service.

// Promote using the interactive method of the CLI
$ subql deployment:promote

// OR using non-interactive method of the CLI, it will prompt you if the required fields are missing
$ subql deployment:promote
  --deploymentID=deploymentID  Enter deployment ID
  --org=org                    Enter organization name
  --project_name=project_name  Enter project name

Delete an Existing Deployment of your Project

This is a command commonly run to clear out data from an existing deployment slot (e.g. the staging slot) before you do a fresh deployment.

// Delete slot using the interactive method of the CLI
$ subql deployment:delete

// OR using non-interactive method of the CLI, it will prompt you if the required fields are missing
$ subql deployment:delete
  --deploymentID=deploymentID  Enter deployment ID
  --org=org                    Enter organization name
  --project_name=project_name  Enter project name