CLI reference

Kata currently provides two commands: ks runs a source file and repl starts an interactive session.

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.

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.

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.