Use the kite CLI¶

The kite command-line interface is the primary utility for executing, validating, testing, and debugging Starkite scripts. It provides dedicated subcommands for inline code evaluation, syntax validation, test harness execution, and hot-reload file watching. The walkthrough below demonstrates these common CLI operations using the local ./hello.star script created in the previous section.

kite version¶

To output the version of the installed kite binary:

$ kite version --short
v0.1.0

Without the --short flag, this command outputs complete build details, including commit hashes, build timestamps, the compiler version, and the target architecture.

kite run¶

The run subcommand executes a Starlark script file end-to-end:

$ kite run ./hello.star
Hello from starkite!
Hostname: dev-host.local
User:     alice
Cwd:      /home/alice/projects/starkite
Kernel:   Linux
Time:     2026-01-15T10:00:00Z
Home:     /home/alice

kite (shorthand)¶

For convenience, if the first positional argument passed to kite is a script file path, the run subcommand is implicit. This makes running the bare file name equivalent to using the explicit run subcommand:

$ kite ./hello.star
Hello from starkite!
Hostname: dev-host.local
User:     alice
Cwd:      /home/alice/projects/starkite
Kernel:   Linux
Time:     2026-01-15T10:00:00Z
Home:     /home/alice

This shorthand is what enables shebang (#!) direct execution. When you execute a script file via ./hello.star, the operating system invokes kite ./hello.star under the hood. Because the run subcommand is assumed automatically, the runtime executes the script directly instead of failing due to a missing subcommand.

For example, given a script with the kite shebang at the top:

#!/usr/bin/env kite
# hello.star
print("Hello from starkite!")
# ...

Executing it directly from the shell:

# Mark the script as executable (if not already done)
$ chmod +x ./hello.star

# Run the script directly using the shebang shorthand
$ ./hello.star
Hello from starkite!
Hostname: dev-host.local
User:     alice
Cwd:      /home/alice/projects/starkite
Kernel:   Linux
Time:     2026-01-15T10:00:00Z
Home:     /home/alice

kite exec¶

The exec subcommand launches an arbitrary external native process or executable script directly under the Starkite kernel sandbox engine, completely bypassing the Starlark interpreter:

$ kite exec /bin/echo "Running inside isolated sandbox"
Running inside isolated sandbox

# Pass child arguments and flags using the POSIX '--' delimiter:
$ kite exec --sandbox-net-allow -- curl -s https://api.github.com/zen

For more details on native process execution, target resolution rules, and stdio streaming, see kite exec.

kite eval¶

The eval subcommand evaluates Starlark expressions and snippets passed directly as an inline string argument:

$ kite eval 'print("Hello from eval")'
Hello from eval

$ kite eval 'print(json.encode({"status": "ok"}))'
{"status":"ok"}

For advanced shell pipelines, JSON/YAML processing, network queries, and script assertions, see the Shell Integration Guide.

kite validate¶

To check a script's syntax without executing any of its logic, use validate. This command parses the script and reports any syntax or structural errors:

$ kite validate ./hello.star
./hello.star: OK

kite test¶

To run test suites written in Starlark, point test at a test script file (typically suffixed with _test.star) or a directory containing them. The runner automatically executes any functions named with the test_ prefix:

# Example running tests against a test file
$ kite test ./hello_test.star
Found 1 test file(s)
============================================================
Tests: 6 passed, 0 failed, 6 total
Time:  15ms
============================================================

For more details on writing test cases and using assertions, see Testing.

kite repl¶

To interactively evaluate Starlark code, launch the read-eval-print loop (REPL) session:

$ kite repl
>>> print(runtime.platform())
darwin
>>>

kite watch¶

To speed up development, watch monitors a script file and automatically re-executes it every time the file is modified:

$ kite watch ./hello.star

For a complete list of CLI subcommands, flags, and environment variables, see the CLI Reference.