SubQuery CLI

... 2022-12-1 About 2 min

# SubQuery CLI

Most customers use the @subql/cli (opens new window) 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:

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:

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

subql help
1

# Prepare your SUBQL_ACCESS_TOKEN

  • Step 1: Go to SubQuery Managed Service (opens new window) 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 (opens new window) 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
1
2
3
4
5
6
7
8
9
10
11
12

# 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]
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 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
1
2
3
4
5
6
7
8

# 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
1
2
3
4
5
6
7
8
Last update: December 1, 2022 23:29