CLI and Debug Flags

Build modes

Build the interpreter with the repo-local helper:

./build.sh

Useful variants already supported by the script:

./build.sh --debug
./build.sh --debug --asan
./build.sh --debug --ubsan
./build.sh --debug --asan --ubsan
./build.sh --release --profiling
./build.sh --release --pgo-generate
./build.sh --release --pgo-use=/tmp/pgo-data

Sanitizers cannot be combined with --lto, --pgo-generate, or --pgo-use.

Running code

kelvra run path/to/program.kel

Add extra package roots when needed:

kelvra run --package-path /path/to/packages app.kel

Check the installed runtime and native package ABI before diagnosing package compatibility issues:

kelvra --version
# kelvra 0.2.0 (native ABI 3)

kelvra version and kelvra -V print the same version line.

Runtime and diagnostics flags

The current interpreter exposes these runtime/debugging switches:

--trace
--show-return
--disassemble
--frontend-timings
--frontend-timings-json
--target <triple>
--prefer-prebuilt
--no-native-build
--cmake-toolchain <path>

Examples:

./build/interpreter --trace tests/sample_var.kel
./build/interpreter --show-return tests/sample_var.kel
./build/interpreter --disassemble tests/sample_var.kel
./build/interpreter --frontend-timings tests/sample_var.kel
./build/interpreter --frontend-timings-json tests/sample_var.kel
./build/interpreter run --target linux-arm64-gnu --cmake-toolchain ./toolchains/linux-arm64.cmake app.kel

The shell test suite verifies that these flags still execute the target program while emitting their extra diagnostics.

Current package-management commands include:

version
init
add
remove
install
update
test
build
run
cache ...
publish
audit
registry ...
validate-package

kelvra test and kelvra build run the corresponding root entry from the [scripts] table in kelvra.toml, installing development and build dependencies first. kelvra run installs normal dependencies when needed before executing the program. Use --locked for reproducible lockfile-only resolution and --offline to prohibit network access.

Cache commands include cache status, cache path <user|project|registry|git>, and cache prune; pass --dry-run to preview pruning.

For package-managed native dependencies, kelvra install, kelvra update, and kelvra run also accept:

--target <triple> to pin the selected native artifact target
--prefer-prebuilt to prefer registry-published prebuilt artifacts
--no-native-build to reject source-build fallback
--cmake-toolchain <path> to enable non-host native source-build fallback

Registry publishing accepts:

--signing-key <path> to sign a trusted registry.v2 index during kelvra publish
--target <triple> plus --native-artifact-dir <dir> to publish a prepared native prebuilt bundle for an explicit target

Dependency auditing accepts:

--offline to reuse cached advisory metadata during kelvra audit

Registry management

Hosted registry trust and credentials can now be bootstrapped through kelvra registry instead of hand-editing project manifests:

./build/interpreter registry status default
./build/interpreter registry trust default --key-file ./keys/registry-public-key.toml
./build/interpreter registry login default --token "$KELVRA_TOKEN"
./build/interpreter registry list
./build/interpreter registry untrust default --key-id release-key
./build/interpreter registry logout default

Current registry subcommands:

registry list to show stored user-level registry profiles
registry status <alias> to inspect the effective trust/token state for a project registry
registry trust <alias> --key ... or --key-file ... to add trusted signing keys
registry untrust <alias> --key-id ... to remove user-stored trust
registry login <alias> and registry logout <alias> to manage hosted bearer tokens

Stored trust and hosted tokens live under ~/.config/kelvra/registries.toml, keyed by the normalized registry index, so the same hosted registry can be reused across multiple project-local aliases. The legacy top-level kelvra login and kelvra logout commands remain as compatibility wrappers.

Frontend timings

--frontend-timings reports a readable phase summary that includes parse, symbol collection, import resolution, bind, type-check, HIR lowering, HIR optimization, cache stats, and total frontend time.

--frontend-timings-json emits the same information as JSON.

Package validation

The interpreter also validates package directories:

./build/interpreter validate-package packages/examples/math
./build/interpreter validate-package packages/examples/counter

Intentional non-feature

The repo explicitly tests that --strict is rejected as an unknown option. Kelvra is already strictly typed by default; there is no separate runtime strictness flag today.