// 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.
| name | cli-local-build |
| description | 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. |
| compatibility | Requires Go 1.23+. |
| metadata | {"author":"ethpandaops","version":"1.0"} |
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 skillManage Kurtosis contexts for connecting to different Kurtosis instances. Add, list, switch, and remove contexts. Use when working with multiple Kurtosis environments (local, remote, team shared).
Inspect and manage Kurtosis enclaves. List enclaves, view services and ports, examine file artifacts, dump enclave state for debugging, and clean up. Use when you need to understand what's running inside an enclave or export its state.
Inspect, download, upload, and debug Kurtosis file artifacts. View artifacts in an enclave, download them locally for inspection, upload local files, and troubleshoot file mounting issues. Use when services can't find expected files or configs are wrong.
Lint and format Kurtosis Starlark files. Check syntax, validate docstrings, and auto-format .star files. Use when writing or reviewing Starlark packages to ensure code quality.
View and manage port mappings for Kurtosis services. Check which local ports map to service ports and troubleshoot connectivity. Use when services aren't reachable or you need to find the right port.
Manage Kurtosis Portal for remote context access. Start, stop, and check status of the Portal daemon that enables communication with remote Kurtosis servers. Use when working with remote Kurtosis contexts.