Skip to main content

​
Introduction

Snuba provides a powerful command-line interface (CLI) for managing all aspects of the application, from running services to managing migrations and consuming Kafka streams. The CLI is built using Click and follows a plugin-based architecture where each command is a separate module.

​
CLI Architecture

The Snuba CLI uses a dynamic command loading system defined in snuba/cli/__init__.py:29. Commands are automatically discovered from Python files in the cli directory, with underscores converted to dashes (e.g., rust_consumer.py becomes rust-consumer). 
# Main CLI entry point
snuba [OPTIONS] COMMAND [ARGS]...

​
Available Commands

Snuba provides the following command categories:

​
Core Service Commands

api

Run the main Snuba HTTP API server

admin

Run the administrative web interface

devserver

Start all services for local development

​
Data Processing Commands

consumer

Python-based Kafka consumer for event processing

rust-consumer

High-performance Rust-based consumer

replacer

Process replacement messages for data updates

subscriptions-executor

Execute scheduled subscription queries

​
Database Management

migrations

Manage ClickHouse schema migrations

bootstrap

Initialize Kafka topics and run migrations

​
Command Features

​
Auto-Initialization

All commands automatically initialize Snuba’s core components before execution. This includes:
  • Setting up Sentry error tracking
  • Configuring structured logging
  • Initializing metrics collection
  • Loading storage and dataset factories
The initialization time is tracked and logged for each command execution.

​
Logging Configuration

Most commands support the --log-level option to control output verbosity: 
snuba consumer --log-level debug --storage errors
Available log levels:
  • critical - Only critical errors
  • error - Error messages
  • warning - Warnings and errors
  • info - Informational messages (default)
  • debug - Detailed debugging information
  • trace - Verbose trace-level logging (Rust consumers)

​
API Server

The main HTTP API server that handles query requests: 
snuba api [OPTIONS]
​
--bind
string
Address to listen on in format host:port
​
--debug
flag
Enable debug mode with auto-reload (development only)
​
--log-level
string
Logging level (critical, error, warning, info, debug)
​
--processes
integer
default:"1"
Number of worker processes (min: 1)
​
--threads
integer
Number of threads per process (min: 1)
​
--backlog
integer
Socket connection backlog (min: 128)

​
Examples

# Run in debug mode with auto-reload
snuba api --debug --log-level debug
In debug mode, only a single process and thread can be used. The server will automatically reload when code changes are detected.

​
Bootstrap

Initialize Snuba’s infrastructure by creating Kafka topics and running migrations: 
snuba bootstrap [OPTIONS]
​
--bootstrap-server
string
Kafka bootstrap servers (can be specified multiple times)
​
--kafka/--no-kafka
boolean
default:"true"
Whether to create Kafka topics
​
--migrate/--no-migrate
boolean
default:"true"
Whether to run database migrations
​
--force
flag
required
Required flag to confirm bootstrap operation
​
--log-level
string
Logging level to use

​
Examples

# Initialize everything (Kafka + migrations)
snuba bootstrap --force --bootstrap-server kafka:9092
The --force flag is required as this command can modify infrastructure. Not intended for production use - use targeted migration commands instead.

​
Common Patterns

​
Storage Selection

Many commands require specifying a storage target: 
snuba consumer --storage errors
snuba consumer --storage transactions
snuba rust-consumer --storage outcomes_raw
Available storages can be listed using the entities command.

​
Kafka Configuration

Commands that interact with Kafka support multiple bootstrap servers: 
snuba consumer \
  --storage errors \
  --bootstrap-server kafka1:9092 \
  --bootstrap-server kafka2:9092 \
  --bootstrap-server kafka3:9092

​
Health Checks

Consumer commands support health check files for orchestration: 
snuba rust-consumer \
  --storage errors \
  --consumer-group errors_group \
  --health-check-file /tmp/snuba-health
The consumer will periodically touch this file to indicate it’s healthy.

​
Version Information

Display Snuba version: 
snuba --version

​
Getting Help

Every command supports the --help flag: 
snuba --help              # List all commands
snuba consumer --help     # Command-specific help
snuba migrations --help   # Subcommand help

​
Next Steps

Consumer Commands

Learn about Kafka consumers and event processing

Migrations

Manage database schema changes

Development Server

Set up local development environment

Admin Interface

Administrative tools and interfaces

Build docs developers (and LLMs) love

Get started for freeTalk to us