envio-cloud

CLI tool for Envio's Hosted Service — deploy, manage, and monitor blockchain indexers powered by HyperIndex.

Installation

go install github.com/enviodev/hosted-service-cli@latest

Or build from source:

git clone https://github.com/enviodev/hosted-service-cli.git
cd hosted-service-cli
go build -o envio-cloud .

Quick Start

# Authenticate with GitHub
envio-cloud login

# Set your default organisation (like kubectl namespaces)
envio-cloud config set-org myorg

# List indexers for your organisation
envio-cloud indexer list --org myorg

# View deployment metrics
envio-cloud deployment metrics hyperindex b3ead3a mjyoung114

# Set a default indexer for convenience
envio-cloud config set-indexer myindexer

Context Management

Like kubectl namespaces, envio-cloud lets you set default values for organisation and indexer so you don't have to pass them on every command.

# Set defaults
envio-cloud config set-org myorg
envio-cloud config set-indexer myindexer

# View current context
envio-cloud config get-context

# Commands now use defaults automatically
envio-cloud deployment status abc1234          # org and indexer from context
envio-cloud deployment metrics abc1234         # same

# Flags always override context
envio-cloud deployment status abc1234 --org other-org

# Clear stored context
envio-cloud config clear

Context is stored at ~/.envio-cloud/context.json. Resolution priority: explicit args > --org/--indexer flags > stored context > GitHub login fallback (org only).

Commands

Context

| Command | Description | |---------|-------------| | config set-org <org> | Set default organisation | | config set-indexer <indexer> | Set default indexer | | config get-context | Show current defaults and where they come from | | config clear | Remove stored context |

Authenticated (run envio-cloud login first)

All commands require authentication and verify you are a member of the target organisation.

| Command | Description | |---------|-------------| | login | Authenticate via GitHub OAuth or personal access token | | logout | Remove stored credentials | | token | Display current auth token status | | repos | List repositories linked to your organisation | | indexer list | List indexers in organisations you belong to | | indexer get <name> [org] | View details and deployments for a specific indexer | | indexer commits <name> [org] | List recent commits and their deploy status | | indexer add | Add a new indexer to the platform | | indexer delete <name> [org] | Permanently delete an indexer and all deployments | | indexer settings get <name> [org] | View indexer settings | | indexer settings set <name> [org] | Modify indexer settings | | indexer env list <name> [org] | List environment variables | | indexer env set <name> [org] KEY=VALUE | Set environment variables | | indexer env delete <name> [org] KEY | Remove environment variables | | indexer env import <name> [org] --file .env | Bulk import from file | | indexer security get <name> [org] | View the security configuration | | indexer security enable <name> [org] | Enable IP whitelisting | | indexer security disable <name> [org] | Disable IP whitelisting | | indexer security add-ip <name> [org] <ip> | Add IP to whitelist | | indexer security remove-ip <name> [org] <ip> | Remove IP from whitelist | | indexer security set-prod-only <name> [org] <true\|false> | Restrict whitelist to production | | indexer security api-key status <name> [org] | Show whether API-key auth is enabled | | indexer security api-key enable <name> [org] | Enable API-key authentication | | indexer security api-key disable <name> [org] | Disable API-key authentication | | indexer security api-key list <name> [org] | List API keys (--show-tokens to reveal) | | indexer security api-key add <name> [org] <key-name> | Add a named API key | | indexer security api-key remove <name> [org] <key-name> | Revoke a named API key | | deployment metrics <indexer> <commit> [org] | Real-time indexing metrics per chain | | deployment info <indexer> <commit> [org] | Aggregator configuration (cache, DB exposure) | | deployment status <indexer> <commit> [org] | Sync progress and completion percentage | | deployment endpoint <indexer> <commit> [org] | Get the GraphQL query endpoint URL | | deployment deploy <indexer> <commit> [org] | Manually deploy a specific commit | | deployment promote <indexer> <commit> [org] | Promote a deployment to production | | deployment delete <indexer> <commit> [org] | Permanently delete a deployment | | deployment restart <indexer> <commit> [org] | Restart a running deployment | | deployment logs <indexer> <commit> [org] | Show build or runtime logs | | deployment tags list <indexer> <commit> [org] | List tags on a deployment | | deployment tags set <indexer> <commit> [org] KEY=VALUE ... | Set key/value tags on a deployment | | deployment tags remove <indexer> <commit> [org] KEY | Remove a tag from a deployment |

Authentication

Browser Login (interactive)

envio-cloud login

Opens your default browser for GitHub OAuth. Credentials are stored at ~/.envio-cloud/auth.json. Session tokens are automatically refreshed when expired.

Token Login (CI/CD and automation)

# Via flag
envio-cloud login --token ghp_your_token_here

# Via environment variable
export ENVIO_GITHUB_TOKEN=ghp_your_token_here
envio-cloud login

Required token scopes: read:org, read:user, user:email.

Usage Examples

Monitoring Deployment Metrics

View real-time indexing progress for deployments in your organisation:

# Table output
envio-cloud deployment metrics hyperindex b3ead3a mjyoung114

# JSON output (for scripting/agents)
envio-cloud deployment metrics hyperindex b3ead3a mjyoung114 -o json

# Watch mode - auto-refresh every 10 seconds
envio-cloud deployment metrics hyperindex b3ead3a mjyoung114 --watch

Example output:

Deployment Metrics: mjyoung114/hyperindex (commit: b3ead3a)

CHAIN      PROGRESS   BLOCK HEIGHT   PROCESSED    EVENTS    HYPERSYNC   SYNCED AT
--------   --------   --------       --------     --------  --------    --------
143        100.00%    62456629       62456630     577336    yes         2026-03-18 16:52
999        100.00%    30166822       30166822     1161921   yes         2026-03-18 16:52

Total chains: 2 | Total events: 1739257 | Status: fully synced

Managing Indexer Settings

# View current settings
envio-cloud indexer settings get myindexer myorg

# Change branch and enable auto-deploy
envio-cloud indexer settings set myindexer myorg --branch main --auto-deploy=true

# Disable auto-deploy
envio-cloud indexer settings set myindexer myorg --auto-deploy=false

Environment Variables

# List variables (values masked by default)
envio-cloud indexer env list myindexer myorg

# Show full values
envio-cloud indexer env list myindexer myorg --show-values

# Set variables
envio-cloud indexer env set myindexer myorg ENVIO_API_KEY=abc123 ENVIO_DEBUG=true

# Remove a variable
envio-cloud indexer env delete myindexer myorg ENVIO_DEBUG

# Bulk import from file
envio-cloud indexer env import myindexer myorg --file .env

All environment variable keys must be prefixed with ENVIO_.

API-Key Authentication

Require clients to send an Authorization: Bearer <token> header on every request to the indexer's GraphQL endpoints. Requires a Production tier plan or above.

# Turn it on — an initial key is provisioned automatically
envio-cloud indexer security api-key enable myindexer myorg

# Check the current state (never prints tokens)
envio-cloud indexer security api-key status myindexer myorg

# List keys, then reveal the tokens
envio-cloud indexer security api-key list myindexer myorg
envio-cloud indexer security api-key list myindexer myorg --show-tokens

# Rotate without downtime: add a key, migrate clients, then revoke the old one
envio-cloud indexer security api-key add myindexer myorg production-2026-08
envio-cloud indexer security api-key remove myindexer myorg production-2026-07

# Turn it off — the endpoints stop requiring a token
envio-cloud indexer security api-key disable myindexer myorg

Tokens are only requested from the API when --show-tokens is passed, so a plain listing never puts a secret on the wire. Removing a key revokes it immediately; the last remaining key cannot be removed — disable API-key authentication instead.

Query an endpoint with a key. The host differs per deployment, so read it from deployment endpoint rather than hardcoding one:

curl -X POST "$(envio-cloud deployment endpoint myindexer abc1234 myorg)" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ENVIO_API_KEY" \
  -d '{"query":"{ __typename }"}'

IP Whitelisting

# View current security config (API-key auth and IP whitelist)
envio-cloud indexer security get myindexer myorg

# Add IPs (supports CIDR notation)
envio-cloud indexer security add-ip myindexer myorg 203.0.113.50
envio-cloud indexer security add-ip myindexer myorg 10.0.0.0/8

# Enable whitelisting
envio-cloud indexer security enable myindexer myorg

# Restrict to production deployments only
envio-cloud indexer security set-prod-only myindexer myorg true

# Remove an IP
envio-cloud indexer security remove-ip myindexer myorg 203.0.113.50

Manual Deploys

Disable auto-deploy and deploy specific commits by hand, as with the Deploy button in the UI:

# Turn off automatic deploys on push
envio-cloud indexer settings set myindexer myorg --auto-deploy=false

# See recent commits and their statuses ('inactive' commits can be deployed)
envio-cloud indexer commits myindexer myorg

# Deploy a specific commit
envio-cloud deployment deploy myindexer abc1234 myorg

Deployment Lifecycle

# Check sync progress
envio-cloud deployment status myindexer abc1234 myorg

# Watch until fully synced
envio-cloud deployment status myindexer abc1234 myorg --watch-till-synced

# Promote to production (confirmation required)
envio-cloud deployment promote myindexer abc1234 myorg

# Restart a deployment
envio-cloud deployment restart myindexer abc1234 myorg

# Delete a deployment (confirmation required — type indexer name)
envio-cloud deployment delete myindexer abc1234 myorg

# Skip confirmation for CI/CD
envio-cloud deployment promote myindexer abc1234 myorg --yes

Deployment Tags

Tag deployments with key/value pairs to identify them (e.g. env=staging). Keys and values are limited to 20 characters, values are lowercased, and keys starting with envio are reserved for system use.

# List tags
envio-cloud deployment tags list myindexer abc1234 myorg

# Set one or more tags (existing keys are overwritten)
envio-cloud deployment tags set myindexer abc1234 myorg env=staging team=backend

# Remove a tag by key
envio-cloud deployment tags remove myindexer abc1234 myorg env

Deleting an Indexer

# Permanently delete an indexer and all deployments
envio-cloud indexer delete myindexer myorg

# Skip confirmation (CI/CD)
envio-cloud indexer delete myindexer myorg --yes

Adding an Indexer

# Basic usage
envio-cloud indexer add --name my-indexer --repo my-linked-repo

# With all options
envio-cloud indexer add \
  --name my-indexer \
  --repo my-linked-repo \
  --description "My blockchain indexer" \
  --branch main \
  --tier development \
  --env-file .env \
  --auto-deploy

# Dry run to preview config
envio-cloud indexer add --name my-indexer --repo my-repo --dry-run

Viewing Repositories

# List linked repositories
envio-cloud repos

# JSON output
envio-cloud repos -o json

Confirmation Prompts

Dangerous commands prompt for confirmation before executing:

• deployment delete and indexer delete: Requires typing the indexer name to confirm
• deployment promote and deployment restart: Requires y/N confirmation

All confirmation prompts can be skipped with the --yes / -y flag for CI/CD usage.

JSON Output

All read commands support -o json for machine-readable output, making it easy to integrate with scripts, CI/CD pipelines, and AI agents:

# Pipe metrics to jq
envio-cloud deployment metrics hyperindex b3ead3a mjyoung114 -o json | jq '.[].num_events_processed'

# Check sync status in a script
PROGRESS=$(envio-cloud deployment metrics hyperindex b3ead3a mjyoung114 -o json | jq '.[0].latest_processed_block')

Global Flags

| Flag | Description | |------|-------------| | --org | Override default organisation | | --indexer | Override default indexer | | -q, --quiet | Suppress informational messages, output data only | | -o, --output | Output format: json (on supported commands) | | --config | Config file path (default: ~/.envio-cloud.yaml) | | -h, --help | Help for any command | | -v, --version | Print version |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success (including empty results) | | 1 | User error (bad arguments, not logged in) | | 2 | API or server error |

Environment Variables

| Variable | Description | |----------|-------------| | ENVIO_GITHUB_TOKEN | GitHub token for non-interactive authentication | | ENVIO_GITHUB_CLIENT_ID | GitHub OAuth app client ID | | ENVIO_GITHUB_CLIENT_SECRET | GitHub OAuth app client secret |

Configuration

Configuration is stored in ~/.envio-cloud.yaml (optional). All settings can also be provided via environment variables with the ENVIO_ prefix.

Context (default org and indexer) is stored separately at ~/.envio-cloud/context.json.

Documentation

• Envio Documentation
• HyperIndex Overview
• Hosted Service Guide

License

Copyright 2025 Envio — [email protected]