Build and test the Kurtosis CLI from source. Compile the CLI binary locally, run it against Docker or Kubernetes engines, and iterate on CLI changes without creating a release. Use when developing or debugging CLI commands.
Build and test the Kurtosis CLI from source for local development.
# Build the CLI binary
go build -o /tmp/kurtosis ./cli/cli/
# Verify it works
/tmp/kurtosis version
The locally built CLI works exactly like the installed one. Use the full path to avoid conflicts with the system-installed kurtosis:
# Start engine
/tmp/kurtosis engine start
# Run a package
/tmp/kurtosis run github.com/ethpandaops/ethereum-package
# Clean up
/tmp/kurtosis clean -a
# Stop engine
/tmp/kurtosis engine stop
# Check current cluster setting
/tmp/kurtosis cluster get
# Switch to Docker
/tmp/kurtosis cluster set docker
# Switch to Kubernetes (uses current kubectl context)
/tmp/kurtosis cluster set kubernetes
# Restart engine after switching
/tmp/kurtosis engine restart
# Verify engine is running on the expected backend
/tmp/kurtosis engine status
/tmp/kurtosis cluster get
For debugging concurrency issues:
go build -race -o /tmp/kurtosis ./cli/cli/
# Run CLI command tests
go test ./cli/cli/commands/...
# Run a specific test
go test -run TestName ./cli/cli/commands/...
# Run with verbose output
go test -v ./cli/cli/commands/...
| Component | Path |
|---|---|
| CLI entry point | cli/cli/main.go |
| CLI commands | cli/cli/commands/ |
| Engine launcher | engine/launcher/ |
| API container launcher | core/launcher/ |
| Container engine abstraction | container-engine-lib/ |
| gRPC API definitions | api/protobuf/ |
| Version constant | kurtosis_version/kurtosis_version.go |
The monorepo has multiple Go modules. If you change a dependency, rebuild in order:
container-engine-lib
→ contexts-config-store
→ grpc-file-transfer
→ name-generator
→ api
→ metrics-library
→ engine
→ core
→ cli
Most CLI-only changes just need go build ./cli/cli/.
go build fails with import errors: Run go mod tidy in the failing module directorykurtosis_version/kurtosis_version.go — it's compiled into the binaryk8s-dev-deploy skill