Skip to content
clstr.io

CLI

The clstr CLI runs tests, manages your progress, and lets you inspect what’s happening inside your cluster. This guide covers installation and the commands you’ll use day to day.

Installation

Section titled “Installation”

go install

Section titled “go install”
Terminal window
$ go install github.com/clstr-io/clstr/cmd/clstr@latest

This installs clstr to your $GOPATH/bin directory. Make sure it’s in your $PATH.

You can also install a specific version using tags (see available versions):

Terminal window
$ go install github.com/clstr-io/clstr/cmd/clstr@v0.4.14

Update

Section titled “Update”
Terminal window
$ go install github.com/clstr-io/clstr/cmd/clstr@latest

Homebrew

Section titled “Homebrew”
Terminal window
$ brew tap clstr-io/tap
$ brew install clstr-io/tap/clstr

Update

Section titled “Update”
Terminal window
$ brew upgrade clstr-io/tap/clstr

Verify Installation

Section titled “Verify Installation”
Terminal window
$ clstr list
Available challenges:


  kv-store             - Distributed Key-Value Store (8 stages)


Start with: clstr init <challenge> --language <lang>

Quick Start

Section titled “Quick Start”
Terminal window
$ clstr init kv-store --language go    # Create challenge in current directory
$ clstr test                           # Test your implementation
$ clstr logs                           # View interleaved logs from all nodes
$ clstr next                           # Advance to the next stage

Commands support short aliases: clstr i, clstr t, clstr n, clstr s, and clstr l / clstr ls.

Basic Workflow

Section titled “Basic Workflow”

Pick a Challenge

Section titled “Pick a Challenge”
Terminal window
$ clstr init <challenge> --language <lang> [path]

Creates a new challenge directory with:

  • Dockerfile - Builds and runs your server in a container
  • README.md - Challenge overview and requirements
  • clstr.yaml - Tracks your progress
Terminal window
$ clstr init kv-store --language go          # Create in current directory
$ clstr init kv-store my-kvs --language go   # Create in ./my-kvs
$ clstr init kv-store --language python      # Create with a Python Dockerfile
$ clstr init kv-store my-kvs --language rust # Create in ./my-kvs with a Rust Dockerfile

Build in Any Language

Section titled “Build in Any Language”

Write your server in any language. Update the Dockerfile to build and start it.

Run the Tests

Section titled “Run the Tests”
Terminal window
$ clstr test

When tests pass:

PASSED ✓


Run clstr next to advance to the next stage.

When they fail, clstr shows what went wrong:

FAILED ✗


PUT http://n1:8080/kv/ "foo"
  Expected: "key cannot be empty"
  Actual: ""


  Your server accepted an empty key when it should reject it.
  Add validation to return 400 Bad Request for empty keys.


Read the guide: https://clstr.io/kv-store/http-api

Fix the error and run clstr test again. The CLI is designed for quick iteration: just keep running clstr test as you make changes.

Advance

Section titled “Advance”
Terminal window
$ clstr next

Advances to the next stage after verifying the current stage passes. Updates clstr.yaml automatically.

clstr next always runs tests first and only advances if they pass.

Commands Reference

Section titled “Commands Reference”

Run clstr --help to see all available commands, or clstr <command> --help for command-specific options.

clstr init

Section titled “clstr init”

Usage: clstr init <challenge> [path]

Creates a new challenge in the specified directory (or current directory if not specified).

Flags:

  • --language, --lang, -l - Generate a Dockerfile for the specified language (e.g., go, python, rust)

clstr test

Section titled “clstr test”

Usage: clstr test [stage]

Runs tests for the current stage (from clstr.yaml) or a specific stage if provided.

Flags:

  • --so-far - Test all stages up to and including the specified stage
Terminal window
$ clstr test                           # Test current stage
$ clstr test leader-election           # Test specific stage
$ clstr test leader-election --so-far  # Test all stages up to & including leader-election

clstr logs

Section titled “clstr logs”

Usage: clstr logs [node...]

Shows logs from all nodes interleaved by timestamp, with relative times from the first log entry. Logs persist across restarts within a run, so lifecycle events (starts, stops, kills, restarts, partitions) appear inline in the timeline alongside application logs.

Cluster-wide events are prefixed [**] and include [CLUSTER READY] (when all nodes finish starting), [TEST: ...] (at the start of each test), and network events like partitions and repairs. These always appear even when filtering by node.

With no arguments shows all nodes. Pass node names to filter:

Terminal window
$ clstr logs           # All nodes interleaved
$ clstr logs n2 n4     # Only n2 and n4

For example, a 3-node run with a leader crash and partition:

[n1]  +0.000s     [START]
[n2]  +0.000s     [START]
[n3]  +0.000s     [START]
[n1]  +0.124s     Node started addr=10.0.42.101:8080
[n2]  +0.131s     Node started addr=10.0.42.102:8080
[n3]  +0.139s     Node started addr=10.0.42.103:8080
[**]  +0.458s     [CLUSTER READY]
[**]  +0.458s     [TEST: Leader Election Completes]
[n2]  +2.341s     Became leader term=1
[n1]  +2.343s     Received heartbeat from 10.0.42.102:8080
[n3]  +2.343s     Received heartbeat from 10.0.42.102:8080
[**]  +3.002s     [TEST: New Leader Elected After Leader Crash]
[n2]  +5.000s     [KILL]
[n1]  +5.032s     Election timeout, starting election term=2
[n3]  +5.034s     Election timeout, starting election term=2
[n1]  +5.187s     Became leader term=2
[n3]  +5.188s     Received heartbeat from 10.0.42.101:8080
[n2]  +8.002s     [START]
[n2]  +8.214s     Received heartbeat from 10.0.42.101:8080, stepping down term=2
[n3]  +9.001s     [RESTART: STOP]
[n3]  +9.244s     Node started addr=10.0.42.103:8080
[n3]  +9.251s     Received heartbeat from 10.0.42.101:8080
[**]  +10.000s    [TEST: Partition Enforces Quorum]
[n1]  +10.001s    [PARTITIONED FROM: n3, n4, n5]
[n1]  +11.543s    Election timeout, starting election term=3
[n1]  +12.891s    Election timeout, starting election term=4
[n3]  +12.011s    Election timeout, starting election term=3
[n3]  +12.187s    Became leader term=3
[**]  +14.001s    [TEST: Cluster Converges After Partition Heals]
[n1]  +14.002s    [PARTITION HEALED]
[n1]  +14.215s    Received heartbeat from 10.0.42.103:8080, stepping down term=3

clstr next

Section titled “clstr next”

Usage: clstr next

Advances to the next stage after verifying current stage passes all tests. Updates clstr.yaml automatically.

clstr status

Section titled “clstr status”

Usage: clstr status

Shows challenge progress and next steps:

Terminal window
$ clstr status
Distributed Key-Value Store


Build a distributed key-value store from scratch using the Raft consensus algorithm.


Progress:
✓ http-api           - Store and Retrieve Data
✓ persistence        - Data Survives SIGTERM
✓ crash-recovery     - Data Survives SIGKILL
→ leader-election    - Cluster Elects and Maintains Leader
  log-replication    - Data Replicates to All Nodes
  log-compaction     - System Manages Log Growth
  membership-changes - Add and Remove Nodes One at a Time
  joint-consensus    - Add and Remove Nodes in Bulk


Read the guide: https://clstr.io/kv-store/leader-election


Implement leader-election, then run clstr test.

clstr list

Section titled “clstr list”

Usage: clstr list

Lists all available challenges with stage counts.