CLI

Installation

go install

$ 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):

$ go install github.com/clstr-io/clstr/cmd/clstr@v0.4.0

Update

$ go install github.com/clstr-io/clstr/cmd/clstr@latest

Homebrew

$ brew tap clstr-io/tap
$ brew install clstr-io/tap/clstr

Update

$ brew upgrade clstr-io/tap/clstr

Verify Installation

$ clstr list
Available challenges:

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

Start with: clstr init <challenge-name>

Quick Start

$ clstr init kv-store --language go    # Create challenge in current directory
$ clstr test                           # Test your implementation
$ 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

1. Start a Challenge

$ clstr init <challenge> [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
• .gitignore - Files to .gitignore

Flags:

• --language, --lang, -l - Language to generate a Dockerfile for (e.g. go, python, rust)

Examples:

$ 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

2. Build in Any Language

Update the Dockerfile to build and start your server. You can use any language as long as the container starts your program.

Then test:

$ clstr test

When tests pass:

PASSED ✓

Run 'clstr next' to advance to the next stage.

When tests fail:

FAILED ✗

PUT http://127.0.0.1:45123/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 issues, then run clstr test again. The CLI is designed for quick iteration, just keep running clstr test as you make changes.

3. Advance

$ clstr next

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

It always runs tests first and only advances if they pass.

Commands Reference

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

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

Usage: clstr test [stage]

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

$ clstr test                # Test current stage
$ clstr test persistence    # Test specific stage

Flags:

• --so-far - Test all stages up to and including the specified stage

$ clstr test persistence --so-far    # Test all stages from http-api through persistence

This is useful for regression testing to ensure earlier stages still pass as you progress through the challenge.

clstr logs

Usage: clstr logs <node>

Shows the captured logs for a node after a test run. Logs persist across restarts within a run, so you see the full history even after a crash or partition.

$ clstr logs n1

================ STARTED ================

Node started addr=10.0.42.101:8080
Voted for 10.0.42.104:8080 in term 1
Election timeout, starting election for term 2
Received vote from 10.0.42.105:8080 (2/3)
Received vote from 10.0.42.102:8080 (3/3)
Became leader in term 2

================ KILLED ================


================ STARTED ================

Node started addr=10.0.42.101:8080
Received heartbeat from 10.0.42.102:8080, stepping down in term 3

================ PARTITIONED FROM: n3, n4, n5 ================

Election timeout, starting election for term 4
Received vote from 10.0.42.102:8080 (2/3)
Election timeout, starting election for term 5
Received vote from 10.0.42.102:8080 (2/3)

================ PARTITION HEALED ================

Election timeout, starting election for term 6
Received vote from 10.0.42.102:8080 (2/3)
Received vote from 10.0.42.103:8080 (3/3)
Became leader in term 6

clstr next

Usage: clstr next

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

clstr status

Usage: clstr status

Shows challenge progress and next steps:

$ 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

Usage: clstr list

Lists all available challenges with stage counts.

Understanding clstr.yaml

The state file tracks your progress with a simple format:

challenge: kv-store
stage: persistence

Format: <challenge>:<stage>