Skip to main content

​
Squid CLI

The Squid CLI is a powerful command-line tool for scaffolding, managing, and deploying Squid indexers. It streamlines the development workflow from project creation to production deployment.
The CLI provides a unified interface for all Squid operations, from local development to cloud deployment.

​
Installation

Install the Squid CLI globally: 
npm install -g @subsquid/cli
Verify installation by running sqd --version
Keep your CLI updated to the latest version for access to new features and bug fixes.

​
Core Commands

​
Project Management

​
Initialize New Project

Create a new Squid project from templates or repositories: 
# Create from template
sqd init my-indexer -t evm

# Create from GitHub repository
sqd init my-indexer -t https://github.com/subsquid-labs/showcase01-all-usdc-transfers

# List available templates
sqd init --help
Templates include pre-configured examples for different blockchain types (EVM, Substrate, Solana, etc.).

​
Project Development

Essential commands for development workflow: 
# Install dependencies
sqd install

# Build project
sqd build

# Generate TypeORM models
sqd codegen

# Apply database migrations
sqd migration:apply

# Start development server
sqd serve:dev
Use sqd serve:dev for local development with hot reloading and GraphQL playground access.

​
Process Management

​
Run Processor

Start and manage your indexer processor: 
# Start processor
sqd process

# Run with specific configuration
sqd process:prod
Ensure your database is running before starting the processor. Use docker compose up -d for local development.

​
Database Operations

Manage database migrations and schema changes: 
# Create migration
sqd migration:create

# Apply migrations
sqd migration:apply

# Revert migration
sqd migration:revert
Always test migrations locally before deploying to production.

​
Deployment

​
SQD Cloud Deployment

Deploy your indexer to SQD Cloud: 
# Deploy to SQD Cloud
sqd deploy

# Deploy with custom name
sqd deploy --name my-production-indexer

# Check deployment status
sqd deploy:status
You need to authenticate with SQD Cloud before deploying. Use sqd auth to set up authentication.

​
Configuration

​
squid.yaml

The main configuration file for your Squid project:
squid.yaml
manifestVersion: subsquid.io/v0.1
name: my-indexer
version: 1
description: My awesome indexer

build:
  dockerfile: Dockerfile

deploy:
  addons:
    postgres:
      version: 14
  processor:
    cmd: ["node", "lib/main.js"]
  api:
    cmd: ["npx", "squid-graphql-server"]
The squid.yaml file defines your project’s build and deployment configuration. It’s automatically generated when you create a new project.

​
Environment Variables

Configure your development and production environments:
.env
# Database connection
DB_NAME=squid
DB_PORT=5432
DB_HOST=localhost
DB_USER=postgres
DB_PASS=postgres

# SQD Cloud
SQD_TOKEN=your-token-here
Never commit sensitive environment variables to version control. Use .env files and SQD Cloud secrets for production.

​
Templates

​
Available Templates

Choose from pre-built templates for different blockchain types:

EVM Template

Basic EVM indexer template for Ethereum and EVM-compatible chains

Substrate Template

Substrate blockchain indexer for Polkadot, Kusama, and Substrate chains

Solana Template

Solana blockchain indexer for Solana programs and transactions

Multi-chain Template

Index multiple blockchains in a single project

​
Custom Templates

Use your own templates for specialized use cases: 
# Use custom GitHub repository as template
sqd init my-project -t https://github.com/your-org/custom-template

# Use local directory as template
sqd init my-project -t ./local-template
Custom templates allow you to standardize project structure across your organization and include your specific configurations.

​
Advanced Usage

​
Custom Commands

Define custom commands in commands.json for project-specific workflows:
commands.json
{
  "commands": {
    "build:prod": {
      "description": "Build for production",
      "cmd": ["npm", "run", "build:prod"]
    },
    "test:e2e": {
      "description": "Run end-to-end tests",
      "cmd": ["npm", "run", "test:e2e"]
    }
  }
}
Custom commands are executed using sqd <command-name> and can include any shell commands or scripts.

​
Multi-environment Setup

Configure different environments for development, staging, and production: 
# Development
sqd process --env development

# Staging
sqd process --env staging

# Production
sqd process --env production
Use environment-specific configuration files (e.g., .env.development, .env.production) to manage different settings.

​
Troubleshooting

​
Common Issues

Ensure you have proper permissions and are logged in to SQD Cloud:
sqd auth
Check that your SQD Cloud account has the necessary permissions for the organization.
Clear cache and rebuild: bash sqd clean sqd build
If issues persist, try deleting node_modules and running npm install again.
Check your environment variables and database status: ```bash sqd db:status
<Warning>
  Ensure your database is running and accessible with the correct credentials.
</Warning>
</Accordion>

<Accordion title="Deployment failures">
Check your `squid.yaml` configuration and authentication:
```bash
sqd deploy --dry-run
sqd auth --check

​
Debug Mode

Enable detailed logging for troubleshooting: 
# Enable verbose logging
sqd --verbose process

# Debug specific command
DEBUG=* sqd build
Debug mode provides detailed information about CLI operations, which is helpful for diagnosing issues.

​
Best Practices

Follow these best practices for effective CLI usage:
  • Version Control: Use version control for your Squid projects to track changes and collaborate
  • Local Testing: Always test locally before deploying to SQD Cloud
  • Environment Management: Use environment-specific configurations for different deployment stages
  • CLI Updates: Regularly update CLI to the latest version for new features and bug fixes
  • Monitoring: Monitor deployment logs for issues and performance insights
  • Security: Never commit sensitive credentials to version control
Set up automated testing and deployment pipelines to streamline your development workflow.

​
CLI Reference

​
Global Options

OptionDescription
--help, -hShow help information
--version, -VShow CLI version
--verbose, -vEnable verbose output
--quiet, -qSuppress output

​
Command Categories

Project Commands

  • init - Initialize new project
  • build - Build project
  • clean - Clean build artifacts

Database Commands

  • migration:* - Manage migrations - codegen - Generate TypeORM models

Development Commands

  • serve:* - Start development servers - process - Run processor

Deployment Commands

  • deploy - Deploy to SQD Cloud
  • auth - Manage authentication

​
Complete Command Reference

For detailed information about all available commands: 
sqd --help
Each command also supports --help for specific usage information, e.g., sqd deploy --help.