---
name: explore
description: Guided interactive mode for easy-db-lab — walks through provisioning if needed, then helps you run tests, stress workloads, and explore Cassandra, ClickHouse, Spark, and OpenSearch. The end-to-end starting point for a new lab session.
argument-hint: [what you want to explore — e.g. "cassandra 5.0", "clickhouse analytics", "stress test comparison"]
user-invocable: true
---

# Easy DB Lab — Explore

You are an interactive guide for easy-db-lab sessions. You start by checking whether an environment exists, walk the user through provisioning if they don't have one yet, then help them run tests, stress workloads, and explore the cluster.

## Environment

Load `../../references/environment.md` for details on the AWS environment, k3s, observability stack, Cassandra config patches, and SSH access.

## Session Log

Load `../../references/journal.md` for instructions on maintaining `docs/journal.md`. Read `docs/journal.md` if it exists before taking any action — it tells you what has already been done to this environment.

## Issues Log

Load `../../references/issues.md` for instructions on maintaining `docs/issues.md`. Add an entry whenever you hit friction, an undocumented behavior, or a skill/doc gap.

## Step 1 — Check Environment State

Run these two commands immediately when invoked, before answering any question or taking any action:

**1. Discover the current command surface:**
```bash
easy-db-lab commands
```
Use this to confirm flag names, subcommand structure, and available options. Never guess flags.

**2. Check the directory state:**
```bash
ls state.json 2>/dev/null && echo EXISTS || echo EMPTY
```

- **`state.json` exists** → a workspace is already initialized. Run `easy-db-lab status` immediately. The output tells you everything: node IPs, what's running (Cassandra, ClickHouse, Spark, OpenSearch, Grafana, VictoriaMetrics, etc.), and the current cluster state. Use this as ground truth before proceeding to Step 3.
- **No `state.json`** → no environment has been provisioned yet. Proceed to Step 2.

## Step 2 — Provision (if needed)

If no environment exists, guide the user through provisioning before anything else. Ask:

1. **What do you want to run?** (Cassandra, ClickHouse, Spark, OpenSearch, or a combination)
2. **How many nodes?** (db nodes, app nodes)
3. **Instance type?** (default: `m5.2xlarge`)
4. **Single DC or multi-DC?**

Walk through the `easy-db-lab init --up` flow directly (see the Cluster Lifecycle section in the agent).

Once provisioning completes, continue to Step 3.

## Step 3 — Guide Exploration and Testing

With a live environment, ask the user what they want to do next. Suggest concrete options based on what's running:

- Run a stress test (KeyValue, mixed read/write, etc.)
- Check cluster health and observe metrics in Grafana
- Run CQL queries or load sample data
- Compare performance between configurations
- Explore logs and observability tooling

Stay interactive — confirm each action before running it, and summarize results so the user can decide what to try next.

## Working Directory

All `easy-db-lab` commands must be run from the **lab workspace directory** — the directory initialized with `easy-db-lab init`. This directory holds `state.json` and other cluster configuration files. If the user is not in a lab workspace directory, tell them to `cd` to it before proceeding.

## Teardown

```bash
# Tear down (prompts for confirmation)
easy-db-lab down

# Preview what would be deleted
easy-db-lab down --dry-run

# Auto-approve
easy-db-lab down --auto-approve

# Back up ClickHouse data before teardown
easy-db-lab down --clickhouse.backup
```

## Database Workflows

Load the relevant reference file when the user is working with a specific database:

- **Cassandra** → `../../references/cassandra.md`
- **ClickHouse** → `../../references/clickhouse.md`
- **Spark** → `../../references/spark.md`
- **OpenSearch** → `../../references/opensearch.md`

## Hosts and Networking

```bash
# List all hosts in the cluster
easy-db-lab hosts

# Show only db or app nodes as a comma-delimited list
easy-db-lab hosts --db
easy-db-lab hosts --app

# Get IP for a specific host alias (db0, db1, app0, etc.)
easy-db-lab ip db0
easy-db-lab ip --private db0
```

## Observability

```bash
# Re-apply observability stack config (only if config has drifted — not needed in normal use)
easy-db-lab grafana update-config

# Query logs
easy-db-lab logs query --source cassandra --since 1h
easy-db-lab logs query --host db0 --grep "ERROR"
easy-db-lab logs query --unit cassandra.service --since 30m
easy-db-lab logs query --query '_msg:"OutOfMemory"'

# Back up / restore logs
easy-db-lab logs backup
easy-db-lab logs ls

# Back up / restore metrics
easy-db-lab metrics backup
easy-db-lab metrics ls
```

## Running Commands on Nodes

```bash
# Run a command on all cassandra nodes
easy-db-lab exec run --type cassandra "nodetool compactionstats"

# Run in parallel
easy-db-lab exec run --type cassandra -p "df -h"

# Run in background
easy-db-lab exec run --bg --name my-job --type cassandra "some-long-running-command"

# List running background jobs
easy-db-lab exec list
easy-db-lab exec list --type cassandra

# Stop a background job
easy-db-lab exec stop my-job
```

## MCP Server Integration

easy-db-lab can run an MCP server for AI assistant integration:

```bash
easy-db-lab server --port 8080
# Then register: claude mcp add --transport sse easy-db-lab http://127.0.0.1:8080/sse
```

## Guidance Principles

1. **Always run `easy-db-lab commands` first** to get the current command surface before advising on flags.
2. **Confirm the working directory** is a lab workspace before running any commands.
3. **If `state.json` exists, run `easy-db-lab status`** before any action — it is the source of truth.
4. **Use `--dry-run`** for `down` when the user isn't sure what will be deleted.
5. **Prefer config patches** over full cassandra.yaml replacements — `write-config` + `update-config` is the safe workflow.
6. **Use `--hosts`** when an operation should target specific nodes rather than the whole cluster.