CLI Reference

The Kit command-line interface provides tools for running, compiling, testing, and managing Kit projects. This page documents all available commands and options.

Usage

Run kit help to see all available commands:

$ kit help
Kit Language

Usage: kit <command> [options]

Commands:
  run <file> [options]                Interpret a Kit file
  build <file> [-o <out>]             Compile a Kit file to binary
    --target <target>                   Compilation target: native, wasm
  repl [options]                      Start interactive REPL
    --set-prompt <str>                  Set custom prompt (default: ≫)
    --preload <file>                    Load a Kit file before starting
  test [file]                         Run tests (discovers in . and tests/)
    --coverage                          Enable coverage tracking
    --coverage-format=FMT               Output format: lcov (default) or json
    --coverage-output=PATH              Custom output path (default: coverage.info)
    --file-parallel N                   Run test files in isolated child workers
    --target NAME                       Apply [targets.NAME] and @target filters
  check [file...]                     Type check Kit files; defaults to **/*.kit in cwd
    --incremental                       Use the new incremental check pipeline (work in progress)
    --list-attributes                   List attributes recognized by Kit tools
    --list-lints                        List lint profiles and checks
    --target NAME                       Apply [targets.NAME] and @target filters
    --show-target-files                 Print files selected by target filters and exit
    --show-config                       Print Build.* values and typed [config] declarations
    --export-config PATH                Write Build.* values and typed [config] declarations as JSON
    --lint-profile NAME                 Use lint profile: default, strict, package-release
    --lint W002,S001                    Run only selected lint codes
    --warnings-as-errors                Fail when lint warnings are emitted
  parity [dir]                        Run interpreter/compiler parity checks for Kit sources
    --parallel N                        Number of parallel workers (default: 4)
    --timeout N                         Compiled exec timeout in ms (default: 30000)
    --build-timeout N                   Build timeout in ms; also used for kit run compile time (default: 600000)
    --failures-only                     Only show failures
  test-self [dir]                     Run curated interpreter/compiler parity regressions
    --parallel N                        Number of parallel workers (default: cpu/2)
    --timeout N                         Compiled exec timeout in ms (default: 30000)
    --build-timeout N                   Build timeout in ms; also used for kit run compile time (default: 600000)
    --failures-only                     Only show failures
  doc <file> [-o <out>]               Generate HTML documentation
  doc --format json <file>            Emit structured API metadata for a file
  api [file-or-dir...]                Emit structured API metadata JSON
  il <file>                           Show IL representation (debug)
  script build <file>                 Build a Kit script artifact
  script call <artifact> <export>     Call an exported script function
  bench-build <file>                  Benchmark clean, warm, and release builds
    --runs N                            Number of isolated runs (default: 1)
    --threshold-clean-ms N              Fail if average clean build exceeds N ms
    --threshold-warm-ms N               Fail if average warm build exceeds N ms
    --threshold-release-ms N            Fail if average release build exceeds N ms

Run/Build Options:
  --cache                             Enable IL caching (default for build)
  --no-cache                          Disable IL caching for build
  --debug, -d                         Fast debug build (default for build)
  --release                           Optimized ReleaseFast build
  --timings                           Print coarse build stage timings
  --info                              Print build metrics and diagnostics
  --color=auto|always|never           Colorize --info output (default: auto)
  --info-layout=auto|stacked|wide     Layout for --info output (default: auto)
  --bytecode                          Use experimental bytecode VM (run only, opt-in)
  --no-spinner                        Disable spinner for automated/CI environments
  --safe[=pkg1,pkg2]                  Restrict extern-c/zig FFI to listed packages

Capability Restrictions:
  --allow=cap1,cap2                   Allow only specified capabilities (allowlist)
  --deny=cap1,cap2                    Deny specified capabilities (deny wins over allow)
  --sandbox                           Deny all capabilities (pure computation only)
  Capability names                    file, net, process, concurrency
  Fine-grained                        file-read, file-write, tcp, udp, dns, actor, channel, parallel

Package Management:
  init [name]                         Initialize a new Kit project
  init-ffi [name]                     Initialize a new Kit Zig FFI package
  game new [path]                     Create a Kit Game project
  game dev                            Run a Kit Game development watcher
  game package                        Build and package a Kit Game project
  install                             Install dependencies from kit.toml
  install --production                Install only runtime dependencies
  install --dev <path>                Include dev-dependencies when installing a package path
  update                              Refresh installed dependencies from manifest refs
  add <package>                       Add a dependency
  add --dev <package>                 Add a development dependency
  remove <package>                    Remove a dependency
  remove --dev <package>              Remove a development dependency
  clean                               Remove kit-packages and lock file
  list                                List installed packages
  cache                               Show cache statistics
  cache list                          List cached packages
  cache clear                         Clear the cache

Dependency Management:
  vendor                              Copy dependencies into vendor/ directory
  vendor --dev                        Include dev-dependencies when vendoring
  vendor --force                      Re-vendor all dependencies
  audit                               List all dependencies and their sources
  audit --transitive                  Include transitive dependencies
  check-deps                          Verify vendored deps match checksums

Task Runner:
  task                                List available tasks from kit.toml
  task <name>                         Run a named task
  task --all                          Run all defined tasks
  task --describe <name>              Show task metadata and steps
  task <name> --dry-run               Preview task commands without running them
  task --format json                  List tasks as JSON

Development:
  dev                                 Run format, check, and test steps
  dev --docs                          Check for missing documentation (packages only)
  dev --target NAME                   Run default check/test steps for a target
  doc-test [paths...]                 Run fenced Kit examples from docs as tests
  api --packages <dir>                Emit package API metadata as JSON
  dev --no-spinner                    Disable spinner for automated/CI environments
  release status                      Show first-party package release readiness

Code Formatting:
  format <files...>                   Format Kit source files in place
  format --check <files>              Check if files are formatted (exit 1 if not)

Auto-Fix:
  fix <files...>                      Apply all safe auto-fixes
  fix --diff <files...>               Preview changes (unified diff, no writes)
  fix --check <files...>              Exit 1 if fixable issues exist (for CI)

Toolchain:
  toolchain                           Show toolchain status
  toolchain install                   Install bundled Zig compiler
  toolchain path                      Print path to Zig executable
  upgrade                             Update Kit to the latest release
  upgrade --check                     Check whether a newer Kit is available
  versions                            List installed Kit versions
  use <version>                       Switch the active Kit version
  rollback                            Switch back to the previous Kit version

Language Server:
  lsp                                 Start LSP server (for editor integration)
    --log-level=<level>                 Set log level (debug, info, warn, error)

Other:
  help                                Show this help message
  version                             Show version information

Examples:
  kit run hello.kit                             Interpret a Kit file
  kit run hello.kit --bytecode                  Run with the experimental bytecode VM
  kit build hello.kit -o hello                  Fast cached debug build
  kit script build mod.kit -o mod.kitbc         Build a script artifact
  kit script call mod.kitbc on-update '[1]'     Call a script export
  kit build hello.kit -o hello --release        Optimized build
  kit bench-build hello.kit --runs 3            Benchmark build performance
  kit build hello.kit --target wasm             Compile to WASM
  kit build app.kit --safe=postgres,raylib      Allow FFI only in listed packages
  kit init my-project                           Create a new project
  kit add ../some-package                       Add a local package dependency
  kit add https://github.com/user/some-package.git  Add a Git package dependency
  kit format src/*.kit                          Format files in place
  kit format --check src/*.kit                  Check formatting
  kit task                                      List tasks
  kit task test                                 Run a task
  kit dev                                       Run dev workflow
  kit upgrade --check                           Check for a Kit update

Environment:
  KIT_HOME                            Kit home directory (default: ~/.kit)

kit run

Interpret and execute a Kit file directly without compilation. When run with no file inside a project with an application manifest, kit run executes the manifest entry-point (like cargo run).

kit run and kit build use the same entry semantics. Runnable files either start with a module declaration or, for a module-less executable file, define a top-level main binding. Top-level expressions are evaluated in source order. A final zero-arity value, including main, is auto-invoked when it is referenced as the file's final top-level value.

kit run [options] [file.kit] [program-args...]

Options

--bytecode - Use the experimental bytecode VM instead of the IL interpreter
--cache - Enable IL caching
--allow=cap1,cap2 - Allow only specified capabilities (see Capability Restrictions)
--deny=cap1,cap2 - Deny specified capabilities (deny wins over allow)
--sandbox - Deny all capabilities (pure computation only)
--allow-requested - Allow exactly the capabilities that imported package manifests declare (see Capability Restrictions)
-h, --help - Show command help

Examples

# Run a Kit file
kit run hello.kit

# Run the manifest entry-point of the current application
kit run

# Run with bytecode VM (experimental)
kit run hello.kit --bytecode

# Run with only file access allowed
kit run app.kit --allow=file

# Run with network access denied
kit run app.kit --deny=net

# Run in sandbox mode (pure computation only)
kit run pure-calc.kit --sandbox

The interpreter is ideal for development and scripting. It provides fast startup times and helpful error messages during development.

kit build

Compile a Kit file to an executable via Zig. Supports native binaries and WebAssembly targets.

kit build [options] <file.kit> [-o output]

Options

-o <output> - Specify the output file name (defaults to input file name without extension)
--target <target> - Compilation target: native (default), wasm, or wasm32-wasi
--cache - Enable IL caching for faster subsequent builds
--no-cache - Disable IL caching
--debug, -d - Use a fast debug Zig build
--release - Use an optimized ReleaseFast Zig build
--timings - Print build stage timings
--info - Print build metrics, cache status, and diagnostics
--color <mode> - Build info color mode: auto, always, or never
--info-layout <layout> - Build info layout: auto, stacked, or wide
--no-spinner - Disable the progress spinner (useful for scripts and CI)
--safe[=pkg1,pkg2] - Restrict FFI to listed packages (empty = stdlib only)
--allow=cap1,cap2 - Allow only specified capabilities (see Capability Restrictions)
--deny=cap1,cap2 - Deny specified capabilities (deny wins over allow)
--sandbox - Deny all capabilities (pure computation only)
--allow-requested - Allow the capabilities that package manifests declare
-h, --help - Show command help

Native Compilation

# Compile to native binary
kit build app.kit -o app

# Run the compiled binary
./app

# Default output name (creates 'app' from 'app.kit')
kit build app.kit

# Print build metrics and diagnostics
kit build app.kit --info --info-layout wide

Compiled binaries are standalone executables with no runtime dependencies. The compiler generates optimized Zig code that compiles to native machine code.

Build Info

Use --info when you need to understand what happened during a build. The report includes frontend timing, typecheck details, imported export inference, backend diagnostics, artifact cache reuse, source reachability, and final artifact status. Layout is chosen automatically from terminal width, or can be forced with --info-layout stacked or --info-layout wide.

# CI-friendly build info with no color
kit build app.kit --info --color never --no-spinner

# Compact timing summary
kit build app.kit --timings

WebAssembly Compilation

Kit can compile to WebAssembly for browser deployment, serverless/edge computing, and cross-platform distribution. WASM output uses WASI for system calls.

# Compile to WebAssembly
kit build app.kit --target wasm -o app.wasm

# Run with Node.js WASI
node --experimental-wasi-unstable-preview1 --experimental-wasm-bigint app.wasm

# Run with Wasmtime
wasmtime app.wasm

# Run with Wasmer
wasmer app.wasm

WASM Capabilities

Pure computation: All Kit language features work perfectly
Basic I/O: println works via WASI
File system: Requires WASI runtime with fs access
Networking: Limited to WASI capabilities of the runtime

Use Cases

Browser: Run Kit programs in web browsers (with WASI polyfill)
Edge/Serverless: Deploy to Cloudflare Workers, Fastly Compute, etc.
Sandboxing: Run untrusted code in isolated WASM environment
Cross-platform: Single binary runs on any WASI runtime

Capability Restrictions

Kit supports Pony-like capability restrictions that limit what a program can do at runtime. These flags work with both kit run and kit build.

The flags control which authority tokens are available to code that performs I/O, networking, process execution, FFI, or concurrency. Standard library authority facades reject forged constructors, and package capability checks use the same rules, so programs should derive narrower capabilities from env.root through Auth.* helpers and pass those tokens explicitly.

Flags

--allow=cap1,cap2 - Allow only the specified capabilities (allowlist)
--deny=cap1,cap2 - Deny the specified capabilities (deny wins over allow)
--sandbox - Deny all capabilities (pure computation only)

Capability Categories

Name	Maps To	Description
`file`	FileAuth, FileReadAuth, FileWriteAuth	Full file system access
`file-read`	FileReadAuth	Read files from disk
`file-write`	FileWriteAuth	Write files to disk
`net`	NetAuth, TCPAuth, TCPConnectAuth, TCPListenAuth, UDPAuth, DNSAuth	Full network access
`tcp`	TCPAuth	TCP socket operations
`tcp-connect`	TCPConnectAuth	Outbound TCP connections
`tcp-listen`	TCPListenAuth	Accept inbound TCP connections
`udp`	UDPAuth	UDP socket operations
`dns`	DNSAuth	DNS lookups
`http`	HTTP, Net.HttpAuth	HTTP client/server operations
`process`	ProcessAuth	Execute external processes
`ffi`	Extern/FFI bindings	Foreign function interface (native code)
`env`	EnvAuth	Read/write environment variables
`concurrency`	ConcurrencyAuth, ActorAuth, ChannelAuth, ParallelAuth	Full concurrency access (actors, channels, parallel)
`actor`	ActorAuth	Create actors and supervisors
`channel`	ChannelAuth	Create communication channels
`parallel`	ParallelAuth	Run parallel tasks

Fine-Grained Capabilities

For more precise control, these fine-grained variants can be used instead of the broader categories:

file-read, file-write - Read-only or write-only file access
tcp, tcp-connect, tcp-listen, udp, dns, http - Specific network protocols or operations
actor, channel, parallel - Specific concurrency primitives

Examples

# Allow only file operations
kit run app.kit --allow=file

# Allow file and network, deny process spawning
kit run app.kit --allow=file,net --deny=process

# Deny network access (allow everything else)
kit run app.kit --deny=net

# Sandbox mode: pure computation only
kit run pure-math.kit --sandbox

# Compile with restrictions baked in
kit build app.kit --allow=file -o app
./app  # File ops work, network ops will panic

# Allow exactly what imported package manifests declare
kit run app.kit --allow-requested

Behavior

Default (no flags): All capabilities allowed
--allow without --deny: Only listed capabilities allowed
--deny without --allow: All capabilities except listed ones allowed
Both --allow and --deny: Deny wins if a capability is in both lists
--sandbox: Overrides all other flags, denies everything
--allow-requested: Grants exactly the capabilities that imported package manifests declare, for this invocation only. --deny and --sandbox still win, and the root project's own extern declarations still require an explicit --allow=ffi. Available on run, build, check, and test.

Missing package capabilities are collected across every imported package during compilation and reported together: one C004 per offending package, plus a combined --allow command when more than one package is involved, so you never have to discover flags one rerun at a time.

On an interactive terminal, Kit also offers a trust-on-first-use consent flow: the first run of a project prompts with the full set of capabilities requested across its dependency manifests, and a grant persists in ~/.kit/consents/ (keyed by the manifest path). Later runs are silent until the requested set grows, in which case the prompt returns showing only the new capabilities. Grants use --allow-requested semantics: package-declared capabilities only, deny and sandbox win, and the root project's extern declarations still need --allow=ffi. Declining stores nothing. Non-TTY runs (CI, scripts) never read or write the consent store, and explicit --allow/--deny/--sandbox/--allow-requested flags skip the flow. The consent file is human-auditable; delete it to revoke.

For compiled binaries, capability restrictions are baked in at compile time. Denied or missing capabilities are reported with capability diagnostics or runtime errors at the protected call site. Constructor forgery is blocked outside test blocks, including through imported packages, so authority should flow through explicit parameters instead of global constructors.

When a guarded operation needs lexical capability evidence, use using auth => body around the operation. The CLI flags decide which capability categories may be available at runtime; using makes an already derived authority token visible to capability checks inside the expression body.

kit repl

Start an interactive Read-Eval-Print Loop for experimenting with Kit.

kit repl [options]

Options

--set-prompt <str> - Set custom prompt (default: ≫)
--preload <file> - Load a Kit file before starting

Example Session

$ kit repl
Kit REPL
Type ':quit' to exit, ':help' for help

>> 1 + 2
3

>> double = fn(x) => x * 2
<closure>

>> double 5
10

>> nums = [1, 2, 3, 4, 5]
[1, 2, 3, 4, 5]

>> map double nums
[2, 4, 6, 8, 10]

>> name = "Kit"
Kit

>> "Hello, ${name}!"
Hello, Kit!

>> :quit

kit test

Run tests defined in Kit files.

kit test [options] [file-or-dir...]

When run without arguments, kit test auto-discovers test files in the current directory matching these patterns: test-*.kit, *-test.kit, *.test.kit.

Options

--coverage - Enable test coverage tracking
--coverage-format=FMT - Output format: lcov (default) or json
--coverage-output=PATH - Custom output path (default: coverage.info for LCOV, coverage.json for JSON)
--format FMT - Test output format: pretty, json, or tap
--filter PATTERN - Run tests whose names contain the pattern
--level L1|L2|L3 - Run tests with the selected level metadata
--list - List selected tests without running them
--parallel N - Number of parallel workers
--file-parallel N - Run test files in isolated child workers
--target NAME - Apply [targets.NAME] and @target filters
--allow=cap1,cap2 - Allow only specified capabilities
--deny=cap1,cap2 - Deny specified capabilities
--sandbox - Deny all capabilities
--allow-requested - Allow the capabilities that package manifests declare
-h, --help - Show command help

Examples

# Run all tests in current directory (auto-discovery)
kit test

# Run a specific test file
kit test tests.kit

# Run tests in a subdirectory
kit test path/to/test-file.kit

# Run tests with coverage tracking
kit test --coverage

# Run tests with JSON coverage output
kit test --coverage --coverage-format=json

# Run tests with custom coverage output path
kit test --coverage --coverage-output=reports/coverage.info

Test File Example

# tests.kit
test "addition works" =>
  assert-eq! 3 (1 + 2)

test "list operations" =>
  xs = [1, 2, 3]
  assert-eq! 3 (length xs)

$ kit test tests.kit
Running 2 test(s) from tests.kit (2 threads)

  PASS addition works
  PASS list operations

All 2 test(s) passed!

Test Coverage

Enable coverage tracking with --coverage to measure which lines and functions are executed during tests. Coverage reports can be generated in LCOV format (compatible with tools like genhtml, Codecov, and Coveralls) or JSON format for custom processing.

$ kit test --coverage tests.kit
Running 2 test(s) from tests.kit (2 threads)

  PASS addition works
  PASS list operations

All 2 test(s) passed!

Coverage: 45/52 lines (86.5%), 8/10 functions (80.0%)
Report written to: coverage.info

See the Testing guide for more details on writing tests and coverage reporting.

kit dev

Run a convention-based development workflow that automatically executes format, check, and test commands based on your project structure.

kit dev [options]

Options

--docs - Only run documentation checks
--no-spinner - Disable the progress spinner
--target NAME - Apply [targets.NAME] and @target filters to default check/test steps
--verbose, -v - Show native build tool output when native setup fails

Default Behavior

When run without custom tasks defined, kit dev automatically:

If src/ exists: runs kit format --check and kit check on source files
If tests/ exists: runs kit test
If zig/build.zig exists (FFI-zig package): runs zig build test

Custom Tasks

You can customize the workflow by defining tasks in your kit.toml:

[tasks]
format = "kit format src/*.kit"
check = "kit check --no-spinner src/*.kit"
test = "kit test tests/"

Tasks named format, check, test, or zig-test override the default commands. Define a custom check task when your package needs a narrower typecheck target than the default source discovery.

kit task

Run tasks defined in your kit.toml file.

kit task [options] [task-name]

Options

name - Run a specific task by name
--all - Run all defined tasks in sequence
--describe <name> - Show task metadata and steps
--dry-run - Preview commands without running them
--format json - List tasks as JSON

Examples

# List available tasks
kit task

# Run a specific task
kit task test

# Run all tasks
kit task --all

# Inspect or preview a task
kit task --describe ci
kit task ci --dry-run
kit task --format json

Task Definition

Tasks are defined in the [tasks] section of kit.toml:

[tasks]
# Simple string command
test = "kit test tests/"
check = "kit check --no-spinner src/*.kit"
format = "kit format src/*.kit"

# Composite task (array of other task names, runs in sequence)
ci = ["format", "check", "test"]

# Object form with metadata
lint = { run = "kit check --lint-profile strict src/*.kit", description = "Run strict lint checks", category = "ci" }
release-check = { steps = ["format", "lint", "test"], description = "Run release checks" }

Composite tasks are validated before execution. Missing referenced tasks and cycles are reported as task errors instead of failing partway through a workflow.

kit check

Type check Kit files without running or compiling them.

kit check [options] [file...]

Options

--incremental - Use the incremental check pipeline
--list-attributes - List attributes recognized by Kit tools
--list-lints - List lint profiles and checks
--target NAME - Apply [targets.NAME] and @target filters
--show-target-files - Print files selected by target filters and exit
--show-config - Print Build.* values and typed [config] declarations
--export-config PATH - Write build config metadata as JSON
--lint-profile NAME - Use lint profile: default, strict, or package-release
--lint CODES - Run only selected comma-separated lint codes
--warnings-as-errors - Fail when lint warnings are emitted
--no-spinner - Disable the progress spinner (useful for scripts and CI)
--allow=cap1,cap2 - Allow only specified capabilities
--deny=cap1,cap2 - Deny specified capabilities
--sandbox - Deny all capabilities
--allow-requested - Allow the capabilities that package manifests declare
-h, --help - Show command help

When run without file arguments, kit check now recursively discovers **/*.kit files in the current working directory.

Examples

$ kit check
# Recursively checks .kit files in the current directory

$ kit check app.kit src/lib.kit
# No output means success

# When there's an error:
$ kit check broken.kit
[T001] Error: Unbound variable
  [broken.kit:1:11]
1 │ message = greeet "World"
              ~~~~~~

Use kit check to validate your code before running or compiling. It catches type errors using Hindley-Milner type inference.

kit parity

Run interpreter/compiler parity checks for Kit source files. This command is intended for examples, regression suites, and any place where you want to verify that interpreted and compiled execution stay aligned.

kit parity [dir] [--parallel <n>] [--timeout <ms>] [--build-timeout <ms>] [--failures-only] [--no-spinner]

Options

dir - Optional directory containing Kit sources to check
--parallel <n> - Number of parallel workers (default: 4)
--timeout <ms> - Compiled execution timeout in milliseconds (default: 30000)
--build-timeout <ms> - Build timeout in milliseconds for compile steps
--failures-only - Only show failures
--no-spinner - Disable the progress spinner

Capability flags are accepted for compatibility, but parity runs always allow all capabilities so the comparison focuses on behavior rather than sandbox restrictions.

Examples

# Run parity checks in the default examples location
kit parity

# Run parity checks for a specific directory
kit parity examples/

# Show only failures and extend build timeout for slower suites
kit parity examples/ --failures-only --build-timeout 600000

Related command: kit test-self [dir] runs the curated interpreter/compiler parity regression suite with the same timeout and filtering flags.

kit format

Format Kit source files with consistent style.

kit format [options] <files...>
kit fmt [options] <files...>

Options

--check - Check if files are formatted without modifying them (exits with code 1 if unformatted)
--indent-width <n> - Set indent width in spaces (default: 2)
-h, --help - Show command help

Supported File Types

.kit - Kit source files (formats entire file)

Examples

# Format a single file
kit format src/main.kit

# Format multiple files
kit format src/*.kit

# Check if files are formatted (useful in CI)
kit format --check src/*.kit

# Use custom indent width
kit format --indent-width 4 src/main.kit

The formatter applies consistent spacing around operators, proper indentation for multi-line expressions, and preserves comments. It's idempotent—running it twice produces the same result.

kit fix

Apply safe lint auto-fixes to Kit source files.

kit fix [options] <files...>

Options

--diff - Preview changes without writing
--check - Exit 1 if fixable issues exist
--no-spinner - Disable the progress spinner
-h, --help - Show command help

Examples

# Apply safe fixes
kit fix src/*.kit

# Preview fixes without writing
kit fix --diff src/*.kit

# Fail CI if safe fixes are available
kit fix --check src/*.kit

kit doc

Generate documentation for a Kit file or src/ directory.

kit doc [options] [file.kit]

Options

--format html|json - Output format
--output <path> - Output path
-o <output> - Output path
-h, --help - Show command help

Example

# Generate documentation
kit doc src/lib.kit -o docs/api.html

kit api

Emit structured API metadata for Kit source files or packages.

kit api [options] [file-or-dir...]

Options

--packages <dir> - Scan all packages under a source package directory
--format json - Output JSON metadata
--output, -o <path> - Write JSON metadata to a file
--no-spinner - Accepted for CI command parity
-h, --help - Show command help

Examples

# Emit API metadata for a source directory
kit api src/

# Emit package API metadata
kit api --packages ../packages --format json -o packages-api.json

kit doc-test

Run fenced Kit examples from Markdown files and ## doc comments as tests.

kit doc-test [options] [file-or-dir...]

Options

--format pretty|json - Output format
--output, -o <path> - Write aggregate JSON results
--no-spinner - Accepted for CI command parity
-h, --help - Show command help

Examples

# Run doc tests in docs and src
kit doc-test docs/ src/

# Write JSON results
kit doc-test docs/ --format json -o doc-test-results.json

kit il

Show the Intermediate Language (IL) representation of a Kit file. Useful for debugging and understanding how Kit code is compiled.

kit il <file>

kit script

Build and run capability-gated Kit script artifacts through the bytecode VM.

kit script build <file.kit> [-o output.kitbc]
kit script call <file.kitbc> <export-name> [json-args]
kit script exports <file.kitbc>

Examples

# Build a script artifact
kit script build mod.kit -o mod.kitbc

# Call an exported function with JSON arguments
kit script call mod.kitbc on-update '[1]'

kit bench-build

Benchmark clean, warm, and release builds for a Kit file.

kit bench-build [options] <file.kit>

Options

--runs N - Number of isolated runs
--threshold-clean-ms N - Fail if average clean build exceeds N ms
--threshold-warm-ms N - Fail if average warm build exceeds N ms
--threshold-release-ms N - Fail if average release build exceeds N ms
-h, --help - Show command help

Examples

# Run three isolated build benchmarks
kit bench-build hello.kit --runs 3

kit lsp

Start the Language Server Protocol (LSP) server for IDE integration. The LSP server provides rich editor features like autocomplete, hover information, diagnostics, parser recovery for incomplete code, and quick fixes for common edits.

kit lsp [options]

Options

--log-level=debug - Enable debug logging for troubleshooting
--log-level=info - Standard logging (default)
--log-level=warn - Only log warnings and errors
--log-level=error - Only log errors

Features

Diagnostics - Real-time error and warning reporting as you type
Hover - Type information and documentation on hover
Go to Definition - Jump to function and variable definitions
Find References - Find all usages of a symbol
Autocomplete - Context-aware completion for identifiers, keywords, imports, and module members
Signature Help - Function parameter hints while typing
Document Symbols - Outline view of file structure
Workspace Symbols - Search symbols across all files
Rename - Rename symbols across files
Code Actions - Quick fixes and refactoring suggestions for common diagnostics
Parser Recovery - Keep diagnostics, completion, and document symbols useful while code is incomplete
Semantic Tokens - Enhanced syntax highlighting
Inlay Hints - Show inferred types inline
Formatting - Format documents via LSP

Editor Setup

VS Code

Install the Kit VS Code Extension which automatically starts the LSP server.

Zed

Install the Kit Zed Extension for full LSP support.

Neovim

-- In your init.lua (nvim-lspconfig)
require('lspconfig.configs').kit = {
  default_config = {
    cmd = { 'kit', 'lsp' },
    filetypes = { 'kit' },
    root_dir = function(fname)
      return lspconfig.util.find_git_ancestor(fname)
        or lspconfig.util.root_pattern('kit.toml')(fname)
    end,
  },
}
require('lspconfig').kit.setup({})

Helix

# In languages.toml
[[language]]
name = "kit"
scope = "source.kit"
file-types = ["kit"]
language-servers = ["kit-lsp"]

[language-server.kit-lsp]
command = "kit"
args = ["lsp"]

Emacs

;; Using lsp-mode
(lsp-register-client
  (make-lsp-client
    :new-connection (lsp-stdio-connection '("kit" "lsp"))
    :major-modes '(kit-mode)
    :server-id 'kit-lsp))

Package Management

Kit includes a built-in package manager for managing dependencies.

kit init

Initialize a new Kit project. By default creates an application with an [application] manifest; use --package for a publishable package with a [package] manifest.

kit init [options] [path]

Options

--name <name> - Project or package name
--path <path> - Target directory
--package - Create a publishable package project with a [package] manifest, examples/, and tests/ directories
-h, --help - Show command help

Application (default)

# Create an application
$ kit init my-app
Created new Kit application: my-app
  + kit.toml
  + src/main.kit
  + .gitignore
  + .editorconfig
  + .tool-versions

The application manifest declares a name, version, and entry-point, plus [dependencies] and [dev-dependencies] sections. Applications are not publishable; their dependencies install project-locally to ./kit-packages/, and a bare kit run executes the manifest entry-point.

# kit.toml for an application
[application]
name = "my-app"
version = "2026.6.30"
entry-point = "src/main.kit"

[dependencies]

[dev-dependencies]

Package Project

# Create a package with manifest
$ kit init my-package --package
Created new Kit package: my-package
  kit.toml
  src/main.kit
  .gitignore
  .editorconfig
  .tool-versions
  examples/
  tests/

Generated Files

kit.toml - Application manifest (default) or package manifest (with --package)
src/main.kit - Entry point with Hello World example
.gitignore - Ignores kit-packages/, build artifacts, OS/editor files
.editorconfig - 2-space indentation for .kit files, UTF-8, LF line endings
.tool-versions - Specifies Zig and Kit versions for version managers (asdf, mise)
examples/ - Example files directory (only with --package)
tests/ - Test files directory (only with --package)

kit init-ffi

Initialize a new Kit Zig FFI package.

kit init-ffi [options] [path]

Options

--name <name> - Package name
--path <path> - Target directory
-h, --help - Show command help

kit game

Project helpers for Kit Game applications.

kit game new [path]
kit game dev
kit game package

Common Options

kit game new --name <name> --title <title> --path <path> - Create a game project
kit game dev --main <file> --asset <path> --source <path> --script-only - Generate or run a development watcher
kit game package --profile <name> --main <file> --output-dir <path> --asset <path> - Build and package a game
-h, --help - Show command help

kit install

Install dependencies or a local package.

kit install [options] [path]

Options

--path <path> - Project or package path
--verbose, -v - Show native build tool output
--force, -f - Force reinstall or rebuild where supported
--dev - Include dev-dependencies for package path installs
--production, --no-dev - Install only runtime dependencies
-h, --help - Show command help

When run without arguments, installs [dependencies] and [dev-dependencies] from kit.toml to the kit-packages/ directory, including transitive dependencies declared by those packages. Use --production or --no-dev to install only runtime dependencies.

When given a path to a local package, installs it to ~/.kit/packages/ (with exclude patterns applied) and installs runtime dependencies by default. Use --dev to include that package's [dev-dependencies] too.

Packages can declare a minimum compatible compiler with a kit-version field in their manifest (e.g., kit-version = ">=2026.6.30"); kit install enforces the pin and reports incompatible packages instead of installing them.

Examples

# Install project dependencies
kit install

# Install only runtime dependencies
kit install --production

# Install a local package globally
kit install /path/to/my-package

# Include dev dependencies for a local package path
kit install --dev /path/to/my-package

kit update

Refresh installed dependencies from kit.toml manifest refs. Locked Git dependencies remain stable during normal kit install; use kit update when you intentionally want to move them.

kit update [options] [path]

Options

--path <path> - Project or package path
--verbose, -v - Show native build tool output
--dev - Include dev-dependencies for package path updates
--production, --no-dev - Update only runtime dependencies
-h, --help - Show command help

kit add

Add a dependency to your project.

kit add [options] <path-or-git-url>

Options

--dev, -D - Add the package to [dev-dependencies] instead of [dependencies]
--init - Create an application kit.toml here if none exists
--tag <tag> - Git tag
--branch <branch> - Git branch
--rev <rev> - Git revision
--name <name> - Dependency name override
-h, --help - Show command help

If no kit.toml exists in the current directory or its parents, kit add offers to create an application manifest (on an interactive terminal) or suggests kit init / --init otherwise.

Examples

# Add a package
kit add ../some-package

# Add a Git dependency at a tag
kit add https://github.com/user/some-package.git --tag v1.2.0

# Add a development-only package
kit add --dev ../test-helper

# Add a package, creating an application manifest if needed
kit add --init ../some-package

kit remove

Remove a dependency from your project.

kit remove [--dev] <package>

Options

--dev, -D - Remove only the matching [dev-dependencies] entry
-h, --help - Show command help

kit clean

Remove the kit-packages/ directory and lock file.

kit clean

kit list

List installed Kit packages from KIT_HOME.

kit list [options]

Options

--names-only, -n - Show only package names
--count, -c - Show package count
--no-header - Hide the column header
-h, --help - Show command help

kit cache

Manage the package cache.

kit cache [command]

Commands

kit cache list - List cached packages
kit cache clear - Clear cached packages
-h, --help - Show command help

Examples

# Show cache statistics
kit cache

# List all cached packages
kit cache list

# Clear the cache
kit cache clear

Dependency Management

Inspect, vendor, and verify project dependencies.

kit vendor

kit vendor [options] [path]

Options

--dev - Include dev-dependencies
--force, -f - Re-vendor existing dependencies
-h, --help - Show command help

kit audit

kit audit [options] [path]

Options

--transitive - Show transitive dependencies
--caps, --capabilities - Audit capability usage in source files
--exports - Include export-level capability and effect summary
--format json - Output audit data as JSON
-h, --help - Show command help

kit check-deps

Verify vendored dependencies against vendor/.checksums.

kit check-deps [path]

kit release status

Show a read-only release readiness dashboard for first-party packages, including each package's git state.

kit release status [options]

Options

--packages PATH - Packages repo root (default: ../packages if present)
--dev-summary PATH - Read tools/packages/run-package-dev-sweep.sh summary TSV
--parity-summary PATH - Read tools/packages/run-package-parity-sweep.sh summary TSV
--only VALUE - Show all, ready, warn, or blockers
--json - Print JSON output
--fail-on-blockers - Exit 1 when any package is blocked
--no-git - Skip per-package git status checks
-h, --help - Show command help

Examples

# Show package readiness and clean/dirty git state
kit release status --packages ../packages

# Emit machine-readable status
kit release status --packages ../packages --json

Toolchain and Version Management

kit toolchain

Manage the bundled Zig compiler dependency.

kit toolchain <command>

Commands

kit toolchain install - Download Zig 0.16.0 and pre-warm build cache
kit toolchain rebuild-runtime - Rebuild the Debug and ReleaseFast build cache
kit toolchain status - Show toolchain status (default)
kit toolchain path - Print path to Zig executable
kit toolchain help - Show command help

kit upgrade

Update Kit to a newer installed release.

kit upgrade [options]

Options

--check - Check whether a newer version is available
--version VERSION - Install a specific version
--force - Reinstall even if the version is already installed
--manifest-url URL - Override update manifest URL
--package-base-url URL - Override GitLab generic package base URL
--help - Show command help

kit versions, kit use, kit rollback

kit versions - List installed Kit versions
kit use <version> - Switch the active Kit version
kit rollback - Switch back to the previous Kit version

Environment Variables

Variable	Description	Default
`KIT_HOME`	Kit home directory for global configuration and cache	`~/.kit`
`KIT_UPDATE_MANIFEST_URL`	Override the update manifest URL used by `kit upgrade`	Release manifest URL
`KIT_UPDATE_PACKAGE_BASE_URL`	Override the package base URL used by `kit upgrade`	GitLab generic package base URL

kit.toml Format

The kit.toml file defines your project's metadata and dependencies.

[package]
name = "my-app"
version = "1.0.0"
authors = ["Your Name"]
description = "A Kit application"

[dependencies]
# Version dependency
json-parser = "1.2.0"

# Repository dependency
my-lib = { git = "https://gitlab.com/user/my-lib", tag = "v1.0" }

# Local path dependency
local-lib = { path = "../local-lib" }

# Files to exclude when published
exclude = ["examples/", "tests/", "*.test.kit"]

CLI Reference

Usage

kit run

Options

Examples

kit build

Options

Native Compilation

Build Info

WebAssembly Compilation

WASM Capabilities

Use Cases

Capability Restrictions

Flags

Capability Categories

Fine-Grained Capabilities

Examples

Behavior

Aggregated Errors and Trust-on-First-Use

kit repl

Options

Example Session

kit test

Options

Examples

Test File Example

Test Coverage

kit dev

Options

Default Behavior

Custom Tasks

kit task

Options

Examples

Task Definition

kit check

Options

Examples

kit parity

Options

Examples

kit format

Options

Supported File Types

Examples

kit fix

Options

Examples

kit doc

Options

Example

kit api

Options

Examples

kit doc-test

Options

Examples

kit il

kit script

Examples

kit bench-build

Options

Examples

kit lsp

Options

Features

Editor Setup

VS Code

Zed

Neovim

Helix

Emacs

Package Management

kit init

Options

Application (default)

Package Project

Generated Files

kit init-ffi

Options