CLI Overview
The real `kira` command surface and the normal developer workflows around it.
The repo currently exposes the toolchain through kira.
The live help text is:
kira <command> [args]
run [--backend vm|llvm|hybrid] [path]
build [--backend vm|llvm|hybrid] [path]
check [path]
tokens [path]
ast [path]
shader check [file.ksl]
shader ast [file.ksl]
shader build [file.ksl]
sync [path]
add <Package>
remove <Package>
update [path]
package pack [path]
package inspect <archive-path|project-dir>
new <Name> <destination>
fetch-llvm
help
versionEveryday Flow
For source iteration:
kira run examples/hello
kira check examples/hello
kira run
kira checkWhen no path is provided, run, build, check, tokens, and ast use the current directory and prefer kira.toml, then legacy project.toml.
For backend-specific execution:
kira run --backend llvm examples/callbacks
kira run --backend hybrid examples/hybrid_roundtripFor shader work:
kira shader check examples/shaders/textured_quad.ksl
kira shader ast examples/shaders/textured_quad.ksl
kira shader build examples/shaders/textured_quad.kslFor artifact creation:
kira build examples/hello
kira build --backend llvm examples/hello
kira build --backend hybrid examples/hybrid_roundtripCLI vs zig build run -- ...
Use kira when you are exercising the installed or managed toolchain.
Use:
zig build run -- ...when you are actively changing the CLI implementation and want each command to run against the just-built in-repo binary.
Logging And Diagnostics
The CLI writes structured KiraLog lines such as:
[info] frontend.started: Frontend compilation started. command=run path=examples/hello/app/main.kiraWhen compilation fails, the CLI renders Kira-native diagnostics with:
- a diagnostic code
- a title
- the source location and caret
- optional help and notes
That is a deliberate design choice: invalid Kira input should fail as Kira, not as a raw Zig panic or linker crash.