kaas-cli 0.1.308

Command line utility for K as a Service

KaaS CLI

Simple Installation

Our deployments can be found on Pypi.

Installation

pip install --user kaas-cli or sudo pip install kaas-cli

For Developers

Prerequisites: python >= 3.11, pip >= 20.0.2, poetry >= 1.3.2.

Installation

To install the package using pip, start by building from Source

make build
pip install dist/*.whl

Installation with uv

uv is a fast Python package manager that can be used as an alternative to pip and poetry.

uv sync

This will create a virtual environment and install all dependencies.

Environment Variables

Configure the CLI by copying the example environment file and setting up the necessary environment variables:

cp .flaskenv.example .flaskenv

Then, edit the .flaskenv file to match your settings.

Usage

After installing the dependencies with poetry install, you can spawn a shell using poetry shell, or alternatively, use make:

make shell
kaas-cli hello
kaas-cli --version

Usage with uv

After installing the dependencies with uv sync, you can run CLI commands directly:

uv run kaas-cli hello
uv run kaas-cli --version

Or activate the virtual environment and use the CLI as usual:

source .venv/bin/activate
kaas-cli hello
kaas-cli --version

To verify the installation, run kaas-cli hello. If you see the message Hello World!, the CLI is set up correctly.

Static Analysis

kaas-cli uses Pyright for static type checking.

make check-pyright
make check

Run Command by Mode

kaas-cli run supports multiple test modes. Flags are mode-specific:

• kontrol: --build-only, --prove-only-profile, --kontrol-version, --kontrol-docker-image, --extra-build-args, --extra-prove-args
• forge: --foundry-version, --foundry-docker-image, --extra-build-args, --extra-test-args
• go (remote only): --fuzz-targets, --go-version, --go-build-directory, --go-module-root, --execution-timeout
• rust (remote only): --fuzz-targets, --rust-version, --rust-build-directory, --rust-fuzz-engine, --rust-fuzz-args, --execution-timeout

Remote Fuzzing Jobs

kaas-cli run supports remote fuzzing with --test-mode go and --test-mode rust.

Use --fuzz-targets with a comma-separated list (up to 5 targets). Each target starts a separate remote job.

The CLI checks available fuzzing capacity before submitting jobs. If the vault's concurrent job limit is reached, you'll see a message indicating how many slots are available.

Go fuzzing

kaas-cli run \
  --mode remote \
  --test-mode go \
  --vault-spec org/vault \
  --token "$KAAS_TOKEN" \
  --branch main \
  --fuzz-targets "^FuzzTransfer$,^FuzzMint$" \
  --go-version 1.23.8 \
  --go-build-directory "./..."

For repositories where go.mod is not at the repo root (e.g. golang/go: module at src/go.mod), set --go-module-root to that directory (e.g. src) and pass --test-root / --go-build-directory relative to it (e.g. ./html/template, not ./src/html/template).

kaas go test shorthand

The kaas go test command mirrors go test -fuzz syntax for a more familiar interface. It supports persistent configuration via .kaas-cli.toml (see below).

kaas go test -fuzz='^FuzzVerifyInteropMessagesValid$' ./op-supernode/supernode/activity/interop/

Multiple fuzz targets can be specified as a comma-separated list:

kaas go test -fuzz='^FuzzTransfer$,^FuzzMint$' ./path/to/pkg/

Each target starts a separate remote job (up to 5 targets).

Additional flags for kaas go test:

• --commit: Pin a specific git commit hash (defaults to HEAD)
• --fuzztime: Go-style duration of at least 1m (e.g. '1m', '5m', '1h'), converted to execution timeout
• --execution-timeout: Execution timeout in minutes (mutually exclusive with --fuzztime)

Rust fuzzing

kaas-cli run \
  --mode remote \
  --test-mode rust \
  --vault-spec org/vault \
  --token "$KAAS_TOKEN" \
  --branch main \
  --fuzz-targets "fuzz_transfer,fuzz_mint" \
  --rust-version stable \
  --rust-build-directory "." \
  --rust-fuzz-engine libfuzzer

Configuration File (.kaas-cli.toml)

The kaas go test command supports persistent configuration via a .kaas-cli.toml file. If no config file is found, the CLI will interactively prompt you to create one.

CLI flags always take priority over config values. The config file is automatically added to .gitignore.

[default]
vault_spec = "org/vault"
token = "your-token"
branch = "main"
url = "https://kaas.runtimeverification.com/"

[go]
go_version = "latest"
go_build_directory = "./..."
go_module_root = "" # optional; e.g. "src" for golang/go stdlib fuzzing
# skip_go_build = true  # optional; skip runner's upfront `go build` (fuzz still uses `go test`)
execution_timeout = 480

Documentation

For detailed usage instructions of the kaas-cli tool, please refer to the official documentation.