Command Reference

run

kira run [--backend vm|llvm|hybrid] [--trace-execution] [--offline] [--locked] [<project-dir|kira.toml|project.toml>]

• default backend: VM
• --backend llvm: builds and runs a native executable
• --backend hybrid: builds a hybrid manifest, bytecode sidecar, and native shared library, then runs the mixed module
• --trace-execution: debug-only stderr trace for VM/native/bridge/trampoline transitions during run
• --offline: use only cached dependencies
• --locked: require the existing lockfile state
• when no path is given, Kira uses the current directory and prefers kira.toml, then legacy project.toml
• the default VM path can print scalar values plus named struct values

--trace-execution is meant for backend debugging. In hybrid mode it makes bridge entry, callback return, struct/class materialization, copy-back, and print-side ownership visible without changing normal program output.

build

kira build [--backend vm|llvm|hybrid] [--offline] [--locked] [<project-dir|kira.toml|project.toml>]

Current output conventions:

• VM: writes generated/<name>.kbc
• LLVM/native: writes a host executable plus its object file
• hybrid: writes generated/<name>.khm, generated/<name>.kbc, a native object file, and a shared library sidecar

check

kira check [--offline] [--locked] [<project-dir|kira.toml|project.toml>]

check does more than syntax-only validation. It currently:

• lexes and parses the file
• resolves imports
• prepares matching native libraries for imported autobinding modules
• runs autobinding generation when those imports require it
• runs semantic analysis

Successful output is simply:

check passed

tokens

kira tokens [<project-dir|kira.toml|project.toml>]

Prints lexer tokens with:

• token kind
• lexeme
• byte range

When no path is given, Kira uses the current directory and prefers kira.toml, then legacy project.toml.

This is useful when you are adjusting syntax or trying to understand a parser failure.

ast

kira ast [<project-dir|kira.toml|project.toml>]

Prints the parsed AST from kira_syntax_model.

Use it when you want to confirm that the parser understood a construct, annotation, or content block the way you expect.

When no path is given, Kira uses the current directory and prefers kira.toml, then legacy project.toml.

shader check

kira shader check [<file.ksl>]

Runs the dedicated .ksl shader lexer, parser, import loader, semantic pass, and typed shader IR validation.

shader ast

kira shader ast [<file.ksl>]

Dumps the parsed KSL module shape without routing through the executable .kira frontend.

shader build

kira shader build [<file.ksl>] [--out-dir <dir>]

• with an explicit .ksl file, emits GLSL 330 vertex/fragment source plus reflection JSON into generated/shaders/ by default
• with no explicit file, discovers top-level PascalCase *.ksl entry shaders under Shaders/ in the current project root and writes outputs to generated/Shaders/
• compute shaders are part of the source language and semantic model, but the current GLSL 330 backend rejects them intentionally with a clear diagnostic

fetch-llvm

kira fetch-llvm

Reads llvm-metadata.toml, chooses the host bundle, downloads the pinned release asset, and installs it under:

~/.kira/toolchains/llvm/<llvm-version>/<host-key>/

sync

kira sync [--offline] [--locked] [<project-dir|kira.toml|project.toml>]

Resolves registry, path, and pinned git dependencies, verifies registry archive checksums, fills the local package cache, and refreshes kira.lock.

add

kira add <Package>
kira add --git <url> --rev <commit> <Package>

Adds a dependency to kira.toml, then resolves and locks the graph.

remove

kira remove <Package>

Removes a dependency from the manifest and refreshes the lockfile.

update

kira update [<project-dir|kira.toml|project.toml>]

Refreshes exact registry versions in the manifest, then re-syncs the lockfile.

package pack

kira package pack [<project-dir|kira.toml|project.toml>]

Writes a validated source-only .tar archive into generated/.

package inspect

kira package inspect <archive-path|project-dir>

Prints package metadata and archive contents in a human-readable form.

new

kira new <Name> <destination>
kira new --lib <Name> <destination>

Scaffolds either an app or a library package.

• kira new DemoApp generated/DemoApp creates an app template
• kira new --lib GraphicsKit generated/GraphicsKit creates a library template

The library scaffold includes:

• kira.toml
• kind = "library"
• module_root = "GraphicsKit"
• app/graphicskit.kira as the root module file

version

kira version

Prints the launcher identity and version string.

help

kira help

Prints the command summary and current install notes.