Powerloom Snapshotter CLI

The Powerloom Snapshotter CLI (powerloom-snapshotter-cli) is a command-line tool that simplifies the process of configuring, deploying, and managing multiple snapshotter instances across different chains and data markets.

tip

The CLI is specifically designed to manage multiple snapshotter instances and replaces the legacy manual setup. It is also perfect for running single snapshotter instances and can safely replace the single node setup.

📖 Overview

✨ Key Features

🚀 Easy Configuration: Set up credentials and settings for different chain/market combinations
📦 Multi-Instance Management: Deploy and manage multiple snapshotter instances
🔍 Instance Monitoring: View status, logs, and diagnostics for running instances
🐚 Interactive Shell: Fast command execution with history support
🔐 Secure Credential Storage: Namespaced environment files for different configurations
🏗️ Identity Management: Generate and manage signer identities

🔄 Command Aliases

The CLI provides multiple command aliases for convenience:

powerloom-snapshotter-cli - Full command name
snapshotter - Short alias

Both commands are equivalent and can be used interchangeably throughout this documentation.

🛠️ Installation

📦 Using Pre-built Binaries (Recommended)

Download the latest binary for your platform from the releases page:
- Linux x86_64: powerloom-snapshotter-cli-linux-amd64
- Linux ARM64: powerloom-snapshotter-cli-linux-arm64
- macOS ARM64 (Apple Silicon): powerloom-snapshotter-cli-macos-arm64
Make the binary executable:
```
chmod +x powerloom-snapshotter-cli-*
```

Move to a directory in your PATH:

# Use the full name
sudo mv powerloom-snapshotter-cli-* /usr/local/bin/powerloom-snapshotter-cli

# Or use a shorter alias for convenience
sudo mv powerloom-snapshotter-cli-* /usr/local/bin/snapshotter

📥 From PyPI Package

# Install using uv (recommended)
uv tool install powerloom-snapshotter-cli

# Or install using pipx
pipx install powerloom-snapshotter-cli

🚀 Quick Start

🪄 Interactive Shell Mode (Recommended)

The CLI has a startup time when running individual commands. We strongly recommend using the interactive shell mode for a much faster and smoother experience:

# Start the interactive shell
powerloom-snapshotter-cli shell

# Now run commands instantly without delays:
powerloom-snapshotter> list
powerloom-snapshotter> configure
powerloom-snapshotter> deploy
powerloom-snapshotter> status

Why Use Shell Mode?

⚡ Instant command execution - No startup delay between commands
📝 Command history - Use arrow keys to navigate previous commands
🔄 Persistent session - Maintains context between commands
🎯 Better workflow - Run multiple operations smoothly

⌨️ Alternative: Individual Commands

If you prefer to run individual commands:

# Configure credentials
powerloom-snapshotter-cli configure --env mainnet --market uniswapv2

# Deploy snapshotter instances
powerloom-snapshotter-cli deploy --env mainnet --market uniswapv2

# Check status
powerloom-snapshotter-cli status

🔍 Example Workflow

Here's a typical workflow for setting up a snapshotter node using the interactive shell:

# Start the interactive shell
powerloom-snapshotter-cli shell

# Show all available data markets and protocol chains
powerloom-snapshotter> list

# In the shell, configure credentials (interactive prompts will guide you)
powerloom-snapshotter> configure

# Deploy your snapshotter instances
powerloom-snapshotter> deploy

# Show status of deployed snapshotter instances (screen sessions and Docker containers). Optionally filter by environment and/or data market.
powerloom-snapshotter> status

# Exit when done
powerloom-snapshotter> exit

💻 Core Commands

📋 Show all available data markets and protocol chains

Shell mode:

powerloom-snapshotter> list

Command line mode:

powerloom-snapshotter-cli list

⚙️ Configure credentials for deployments

Set up credentials and settings for a specific chain and data market combination.

Shell mode:

# Interactive configuration (prompts for all values)
powerloom-snapshotter> configure

Command line mode:

# Interactive configuration
powerloom-snapshotter-cli configure

# With all options specified
powerloom-snapshotter-cli configure --env mainnet --market uniswapv2 --wallet 0x123...

Options:

--env, -e: Powerloom chain name (e.g., devnet, mainnet)
--market, -m: Data market name (e.g., uniswapv2, aavev3)
--wallet, -w: Wallet address holding the slots
--signer, -s: Signer account address
--signer-key, -k: Signer account private key
--source-rpc, -r: Source chain RPC URL
--powerloom-rpc, -p: Powerloom RPC URL

🚀 Deploy snapshotter nodes

Deploy snapshotter nodes for specified environment and data markets.

Shell mode:

# Interactive deployment (prompts for environment and market)
powerloom-snapshotter> deploy

Command line mode:

# Deploy all slots for a market
powerloom-snapshotter-cli deploy --env mainnet --market uniswapv2

# Deploy specific slots
powerloom-snapshotter-cli deploy --env mainnet --market uniswapv2 --slot 123 --slot 456

# Deploy multiple markets
powerloom-snapshotter-cli deploy --env mainnet --market uniswapv2 --market aavev3

📊 Show deployment status

Show status of deployed snapshotter instances (screen sessions and Docker containers). Optionally filter by environment and/or data market.

Shell mode:

powerloom-snapshotter> status

Command line mode:

powerloom-snapshotter-cli status

Output shows:

Instance name
Status (Active/Inactive)
Docker container status
Process details

🔧 Diagnose and cleanup

Run diagnostics on the system and check requirements.

Shell mode:

# Run diagnostics
powerloom-snapshotter> diagnose

Command line mode:

# Run diagnostics
powerloom-snapshotter-cli diagnose

# Clean up existing deployments
powerloom-snapshotter-cli diagnose --clean --force

Checks include:

Python version
System resources (CPU, memory, disk)
Docker installation and status
Network connectivity
Required port availability

🔑 Manage credentials

Manage signer identities and other credentials configured against a specific environment and data market.

Shell mode:

# Show summary of all available identities
powerloom-snapshotter> identity list

# Show details of a specific identity
powerloom-snapshotter> identity show --env mainnet --market uniswapv2

Command line mode:

# Show summary of all available identities
powerloom-snapshotter-cli identity list

# Show details of a specific identity
powerloom-snapshotter-cli identity show --env mainnet --market uniswapv2

📝 Credentials Management: Internals

📁 Configuration Files

Configuration files are stored in ~/.powerloom-snapshotter-cli/envs/ with the naming convention:

.env.{chain}.{market}.{source_chain}

Example: .env.mainnet.uniswapv2.eth_mainnet

🔐 Environment Variables

Each configuration file contains:

WALLET_HOLDER_ADDRESS: Address holding slot NFTs
SIGNER_ACCOUNT_ADDRESS: Address used for signing snapshots
SIGNER_ACCOUNT_PRIVATE_KEY: Private key for signer account
SOURCE_RPC_URL: RPC endpoint for source blockchain
POWERLOOM_RPC_URL: Powerloom protocol RPC endpoint

📊 Comparison with Manual Setup

Feature	Manual Setup	CLI
Multiple slots	Requires multiple repositories	Single command deployment
Configuration	Manual `.env` file editing	Interactive configuration
Monitoring	Check each instance separately	Unified `list` command
Updates	Update each repository	Single CLI update

❓ Troubleshooting

🐛 Common Issues

"Docker daemon is not running"

Start Docker Desktop or the Docker service:

# Linux
sudo systemctl start docker

"No slots found for wallet"

Verify that:

The wallet address owns slots on the specified chain
You're using the correct chain (devnet vs mainnet)
The RPC URL is accessible

"Screen session already exists"

Clean up existing sessions:

powerloom-snapshotter-cli diagnose --clean --force

🔄 Migration from Manual Setup

If you're currently running snapshotter nodes manually, here's how to migrate to the CLI:

Stop and cleanup existing nodes:

# In your existing setup
./diagnose.sh -y

Install the CLI (see Installation section above)

Configure using the CLI:

powerloom-snapshotter-cli configure --env mainnet --market uniswapv2

Deploy using the CLI:

powerloom-snapshotter-cli deploy --env mainnet --market uniswapv2

The CLI will handle all your slots automatically and provide better management capabilities.

📖 Overview​

✨ Key Features​

🔄 Command Aliases​

🛠️ Installation​

📦 Using Pre-built Binaries (Recommended)​

📥 From PyPI Package​

🚀 Quick Start​

🪄 Interactive Shell Mode (Recommended)​

⌨️ Alternative: Individual Commands​

🔍 Example Workflow​

💻 Core Commands​

📋 Show all available data markets and protocol chains​

⚙️ Configure credentials for deployments​

🚀 Deploy snapshotter nodes​

📊 Show deployment status​

🔧 Diagnose and cleanup​

🔑 Manage credentials​

📝 Credentials Management: Internals​

📁 Configuration Files​

🔐 Environment Variables​

📊 Comparison with Manual Setup​

❓ Troubleshooting​

🐛 Common Issues​

"Docker daemon is not running"​

"No slots found for wallet"​

"Screen session already exists"​

🔄 Migration from Manual Setup​

🔗 Additional Resources​

📖 Overview

✨ Key Features

🔄 Command Aliases

🛠️ Installation

📦 Using Pre-built Binaries (Recommended)

📥 From PyPI Package

🚀 Quick Start

🪄 Interactive Shell Mode (Recommended)

⌨️ Alternative: Individual Commands

🔍 Example Workflow

💻 Core Commands

📋 Show all available data markets and protocol chains

⚙️ Configure credentials for deployments

🚀 Deploy snapshotter nodes

📊 Show deployment status

🔧 Diagnose and cleanup

🔑 Manage credentials

📝 Credentials Management: Internals

📁 Configuration Files

🔐 Environment Variables

📊 Comparison with Manual Setup

❓ Troubleshooting

🐛 Common Issues

"Docker daemon is not running"

"No slots found for wallet"

"Screen session already exists"

🔄 Migration from Manual Setup

🔗 Additional Resources