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]

Option	Description	Default
`--db`, `--cassandra`, `-c`	Number of Cassandra instances	3
`--app`, `--stress`, `-s`	Number of stress instances	0
`--instance`, `-i`	Cassandra instance type	r3.2xlarge
`--stress-instance`, `-si`	Stress instance type	c7i.2xlarge
`--azs`, `-z`	Availability zones (e.g., `a,b,c`)	all
`--arch`, `-a`	CPU architecture (AMD64, ARM64)	AMD64
`--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.

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

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

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

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

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

Option	Description	Default
`--sleep`	Time between starts in seconds	120
`--hosts`	Filter to specific hosts	-

Option	Description
`--hosts`	Filter to specific hosts

Option	Description
`--hosts`	Filter to specific hosts

Cassandra Stress Commands

Stress testing commands under cassandra stress.

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>

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.