Command Reference

Complete reference for all easy-db-lab commands.

Global Options

Option	Description
`--help`, `-h`	Shows help information
`--vpc-id`	Reconstruct state from existing VPC (requires ClusterId tag)
`--force`	Force state reconstruction even if state.json exists

Setup Commands

setup-profile

Set up user profile interactively.

easy-db-lab setup-profile

Aliases: setup

Guides you through:

Email and AWS credentials collection
AWS credential validation
Key pair generation
IAM role creation
Packer VPC infrastructure setup
AMI validation/building

show-iam-policies

Display IAM policies with your account ID populated.

easy-db-lab show-iam-policies [policy-name]

Aliases: sip

Argument	Description
`policy-name`	Optional filter: `ec2`, `iam`, or `emr`

build-image

Build both base and Cassandra AMI images.

easy-db-lab build-image [options]

Option	Description	Default
`--arch`	CPU architecture (AMD64, ARM64)	AMD64
`--region`	AWS region	(from profile)

Cluster Lifecycle Commands

init

Initialize a directory for easy-db-lab.

easy-db-lab init [cluster-name] [options]

The database and application node groups are configured through a namespaced --db.* / --app.* scheme. Every pre-existing flag continues to work as an alias carrying its established default. When both a namespaced option and its legacy alias are supplied for the same setting, the namespaced option always wins, regardless of the order they appear on the command line.

Architecture is no longer a flag. Each node group's CPU architecture is derived automatically from that group's resolved instance type at init time (via the EC2 DescribeInstanceTypes SupportedArchitectures field) and persisted per group in cluster state. A cluster whose database and application groups have different architectures is provisioned correctly, each group booting from the AMI for its own architecture. An instance type whose architecture cannot be determined fails at init, before any instance is created.

Option	Description	Default
`--db.count` (alias `--db`, `--cassandra`, `-c`)	Number of database instances	3
`--app.count` (alias `--app`, `--stress`, `-s`)	Number of application instances	0
`--db.instance-type` (alias `--instance`, `-i`)	Database instance type	i4i.xlarge
`--app.instance-type` (alias `--stress-instance`, `-si`)	Application instance type	c6id.2xlarge
`--azs`, `-z`	Availability zones (e.g., `a,b,c`)	all
`--ebs.type`	EBS volume type (NONE, gp2, gp3, io1, io2)	NONE
`--ebs.size`	EBS volume size in GB	256
`--ebs.iops`	EBS IOPS (gp3 only)	0
`--ebs.throughput`	EBS throughput (gp3 only)	0
`--ebs.optimized`	Enable EBS optimization	false
`--until`	When instances can be deleted	tomorrow
`--ami`	Override AMI ID	(auto-detected)
`--open`	Unrestricted SSH access	false
`--tag`	Custom tags (key=value, repeatable)	-
`--vpc`	Use existing VPC ID	-
`--up`	Auto-provision after init	false
`--clean`	Remove existing config first	false

up

Provision AWS infrastructure.

easy-db-lab up [options]

Option	Description
`--no-setup`, `-n`	Skip K3s setup and AxonOps configuration

Creates: VPC, EC2 instances, K3s cluster. Configures the account S3 bucket for this cluster.

up fails fast. If any provisioning step fails — EC2 setup, K3s, node labeling, the local-storage/local-storage-wfc StorageClasses, the observability stack, Tailscale, and so on — the command exits non-zero and stops rather than continuing with a partially-provisioned cluster. EC2 instances that were already launched are left running; there is no automatic rollback. Reclaim them with easy-db-lab down, fix the underlying issue, and re-run up.

down

Shut down AWS infrastructure.

easy-db-lab down [vpc-id] [options]

Argument	Description
`vpc-id`	Optional: specific VPC to tear down

Option	Description
`--all`	Tear down all VPCs tagged with easy_cass_lab
`--packer`	Tear down the packer infrastructure VPC
`--retention-days N`	Days to retain S3 data after teardown (default: 1)

clean

Clean up generated files from the current directory.

easy-db-lab clean

hosts

List all hosts in the cluster.

easy-db-lab hosts

status

Display full environment status.

easy-db-lab status

status is the one command that degrades instead of failing outright when the SOCKS proxy tunnel can't be established. It still reports EC2, VPC, security groups, Spark/EMR, OpenSearch, S3, kits, observability URLs, and database versions — the last read directly over SSH, which never uses the tunnel. Only the sections that require the private Kubernetes API (stress jobs, ClickHouse) are marked unavailable, each stating the proxy failure as the reason. status still exits non-zero when degraded, so a partial report is never mistaken for a healthy cluster by a script. See Network Connectivity for how to diagnose a tunnel that won't come up.

Cassandra Commands

All Cassandra commands are available under the cassandra subcommand group.

cassandra use

Select a Cassandra version.

easy-db-lab cassandra use <version> [options]

Option	Description
`--java`	Java version to use
`--hosts`	Filter to specific hosts

Versions: 3.0, 3.11, 4.0, 4.1, 5.0, 5.0-HEAD, 6.0-HEAD, trunk

cassandra write-config

Generate a new configuration patch file.

easy-db-lab cassandra write-config [filename] [options]

Aliases: wc

Option	Description	Default
`-t`, `--tokens`	Number of tokens	4

cassandra update-config

Apply configuration patch to all nodes.

easy-db-lab cassandra update-config [options]

Aliases: uc

Option	Description
`--restart`, `-r`	Restart Cassandra after applying
`--hosts`	Filter to specific hosts

cassandra download-config

Download configuration files from nodes.

easy-db-lab cassandra download-config [options]

Aliases: dc

Option	Description
`--version`	Version to download config for

cassandra start

Start Cassandra on all nodes.

easy-db-lab cassandra start [options]

Option	Description	Default
`--sleep`	Time between starts in seconds	120
`--hosts`	Filter to specific hosts	-
`--sidecar-image`	Container image for the sidecar DaemonSet	`ghcr.io/apache/cassandra-sidecar:latest`

Use --sidecar-image to test a fork or specific version:

easy-db-lab cassandra start --sidecar-image ghcr.io/myfork/cassandra-sidecar:my-branch

cassandra stop

Stop Cassandra on all nodes.

easy-db-lab cassandra stop [options]

Option	Description
`--hosts`	Filter to specific hosts

cassandra restart

Restart Cassandra on all nodes.

easy-db-lab cassandra restart [options]

Option	Description
`--hosts`	Filter to specific hosts

cassandra list

List available Cassandra versions.

easy-db-lab cassandra list

Aliases: ls

Cassandra Stress Commands

Stress testing commands under cassandra stress.

cassandra stress start

Start a stress job on Kubernetes.

easy-db-lab cassandra stress start [options]

Aliases: run

cassandra stress stop

Stop and delete stress jobs.

easy-db-lab cassandra stress stop [options]

cassandra stress status

Check status of stress jobs.

easy-db-lab cassandra stress status

cassandra stress logs

View logs from stress jobs.

easy-db-lab cassandra stress logs [options]

cassandra stress list

List available workloads.

easy-db-lab cassandra stress list

cassandra stress fields

List available field generators.

easy-db-lab cassandra stress fields

cassandra stress info

Show information about a workload.

easy-db-lab cassandra stress info <workload>

Utility Commands

exec

Execute commands on remote hosts via systemd-run. Tool output is captured by the systemd journal and shipped to VictoriaLogs via a dedicated journald OTel collector, with accurate timestamps for cross-service log correlation.

exec run

Run a command on remote hosts (foreground by default).

# Foreground (blocks until complete, shows output)
easy-db-lab exec run -t cassandra -- ls /mnt/db1

# Background (returns immediately, tool keeps running)
easy-db-lab exec run --bg -t cassandra -- inotifywait -m /mnt/db1/data

# Background with custom name
easy-db-lab exec run --bg --name watch-imports -t cassandra -- inotifywait -m /mnt/db1/data

Option	Description
`-t, --type`	Server type: cassandra, stress, control (default: cassandra)
`--bg`	Run in background (returns immediately)
`--name`	Name for the systemd unit (auto-derived if not provided)
`--hosts`	Filter to specific hosts
`-p`	Execute in parallel across hosts

exec list

List running background tools on remote hosts.

easy-db-lab exec list
easy-db-lab exec list -t cassandra

exec stop

Stop a named background tool.

easy-db-lab exec stop watch-imports
easy-db-lab exec stop watch-imports -t cassandra

ip

Get IP address for a host by alias.

easy-db-lab ip <alias>

version

Display the easy-db-lab version.

easy-db-lab version

repl

Start interactive REPL.

easy-db-lab repl

server

Start the server for Claude Code integration, REST status endpoints, and live metrics.

easy-db-lab server

See Server for details.

Kubernetes Commands

k8 apply

Apply observability stack to K8s cluster.

easy-db-lab k8 apply

Dashboard Commands

dashboards generate

Extract all Grafana dashboard manifests (core and ClickHouse) from JAR resources to the local k8s/ directory. Useful for rapid dashboard iteration without re-running init.

easy-db-lab dashboards generate

dashboards upload

Apply all Grafana dashboard manifests and the datasource ConfigMap to the K8s cluster. Extracts dashboards, creates the grafana-datasources ConfigMap with runtime configuration, and applies everything.