CLI reference

Kata provides interpreter execution, a compiler written in KataScript, a bytecode runtime, live debugging, and declaration introspection.

kata --help
kata --version
kata ks --help

These examples assume kata is on your shell’s PATH. From a source checkout, substitute target/debug/kata or use cargo run -- before the command.

Run a file

kata ks program.ks

The CLI reads a UTF-8 source file, loads the prelude, and evaluates the program. print(...) writes a line to standard output. Normal script execution does not automatically display the value of every expression.

File-read failures, parse errors, and runtime errors produce a nonzero exit status. Diagnostics go to standard error. Host crashes remain possible in the experimental implementation; see language status.

There is currently no command-line facility for passing an argument list into a script, no package runner, and no watch command.

Compile and bootstrap

kata compile program.ks -o program.kbc
kata run program.kbc
kata run program.ks
kata bootstrap
kata run program.ks --compiler target/bootstrap/stage3.kbc

compile and run use the compiler written in KataScript. The compiled language currently covers a bootstrap profile. Unsupported features produce a diagnostic; ks continues to support the broader tree-walk language.

bootstrap rebuilds the compiler through three generations and compares their exact bytes. It writes the compiler sources, KBC artifacts, and a receipt with SHA-256 digests under target/bootstrap/. --out-dir chooses another directory. --compiler runs a previously compiled compiler artifact.

The bootstrap also builds the KVM interpreter written in KataScript. Select that runtime explicitly with kata run program.kbc --vm target/bootstrap/kvm.kbc. Its primitive execution still runs on the Rust seed VM.

Inspect and debug compiled execution

kata inspect program.kbc
kata inspect program.kbc --function main
kata inspect program.kbc --json
kata debug program.ks
kata debug program.kbc --steps 20 --json

inspect verifies the artifact and lists its functions. A function selection prints instructions and source byte spans. The debugger retains actual frames and registers between s [count] (step), c (continue), r, bt, and g (inspect) commands. Use q to exit. --steps executes a bounded number of instructions and reports the resulting state.

Program output stays on stdout; debugger diagnostics and JSON events use stderr. --fuel bounds executed guest instructions. This CLI debugger currently exposes register identities and byte spans; source binding names and breakpoints are future work. The browser playground uses its separate interpreter host.

Inspect the frontend

kata ks program.ks --dump-tokens
kata ks program.ks --dump-ast

Each flag prints JSON and exits without evaluating the program. Token output reveals the lexer’s view of source text; AST output reveals how the parser groups it into expressions and statements.

With jq installed:

kata ks program.ks --dump-ast | jq .

Use one dump flag at a time. If both are supplied, token dumping takes precedence.

Inspect documentation

kata doc example.ks --json
kata doc --check

kata doc reads declarations and adjacent ## docstrings without executing the inspected program. --json emits the structured declaration index; --check runs documented KataScript examples against their expected output. See Docstrings and introspection for the source format, generated API reference, and full checking workflow.

The REPL

kata repl

The REPL uses Reedline with syntax highlighting, multiline input, completion, and persistent command history. Bindings and function definitions remain available within the current session.

Input	Behavior
Tab	Open completion, then advance through candidates
Shift+Tab	Move to the previous completion
Ctrl+C	Cancel the current input
Ctrl+D	Exit the session

The current input-completeness scanner has edge cases around comments and mixed quote characters, and completion has a known Unicode boundary bug. A failed evaluation can also leave unexpected scope state or suppress output produced earlier in that submission. Restart the REPL after a confusing error, and reproduce important behavior in a fresh script.

Logging

The CLI honors RUST_LOG; its default level is warn.

RUST_LOG=debug kata ks program.ks

Logging is for investigating the implementation. Leave it at its default when comparing a script’s output with an expected-output file.