Metadata-Version: 2.1
Name: kaas-cli
Version: 0.1.308
Summary: Command line utility for K as a Service
Author: Runtime Verification, Inc.
Author-email: contact@runtimeverification.com
Requires-Python: >=3.11,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: click (>=8.0.1,<9.0.0)
Requires-Dist: dacite (>=1.8.1,<2.0.0)
Requires-Dist: docker (>=7.1.0,<8.0.0)
Requires-Dist: gql[requests] (>=3.4.0,<4.0.0)
Requires-Dist: hurry-filesize (>=0.9,<0.10)
Requires-Dist: jmespath (>=1.0.1,<2.0.0)
Requires-Dist: pandas (>=2.2.2,<3.0.0)
Requires-Dist: pandas-stubs (>=2.2.2.240603,<3.0.0.0)
Requires-Dist: pytest (>=8.0.1,<9.0.0)
Requires-Dist: pytest-watch (>=4.2.0,<5.0.0)
Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
Requires-Dist: requests (>=2.31.0,<3.0.0)
Requires-Dist: tomlkit (>=0.13.2,<0.14.0)
Requires-Dist: types-jmespath (>=1.0.2.20240106,<2.0.0.0)
Requires-Dist: urllib3 (>=1.25.4,<2.1)
Description-Content-Type: text/markdown

# KaaS CLI

## Simple Installation
Our deployments can be found on [Pypi](https://pypi.org/project/kaas-cli/).

### 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](https://github.com/runtimeverification/kaas)

```bash
make build
pip install dist/*.whl
```

### Installation with uv

[uv](https://docs.astral.sh/uv/) is a fast Python package manager that can be used as an alternative to `pip` and `poetry`.

```bash
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:

```bash
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`:

```bash
make shell
kaas-cli hello
kaas-cli --version
```

#### Usage with uv

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

```bash
uv run kaas-cli hello
uv run kaas-cli --version
```

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

```bash
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.

```bash
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

```bash
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).

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

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

```bash
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

```bash
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`.

```toml
[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](https://docs.runtimeverification.com/kaas/guides/kaas-cli_connecting-using-tokens).

