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> [--bytecode] Interpret a Kit file
  build <file> [-o out] [--target native|wasm]
                          Compile to native code or WebAssembly
  repl                    Start interactive REPL
  test [file]             Run tests (auto-discovers if no file given)
  check <file>            Type check a Kit file
  format <files...>       Format Kit source files
  doc <file> [-o out]     Generate HTML documentation
  il <file>               Show IL representation (debug)
  lsp                     Start the Language Server Protocol server

Common Options:
  --no-spinner            Disable progress spinner (for build/check)
  --bytecode              Use experimental bytecode VM (for run)

Test Options:
  --coverage              Enable coverage tracking
  --coverage-format=FMT   Output format: lcov (default) or json
  --coverage-output=PATH  Custom output path (default: coverage.info)

Package Management:
  init [name] [--package] Initialize a new Kit project or package
  install [path]          Install dependencies or a local package
  add <package>           Add a dependency
  remove <package>        Remove a dependency
  clean                   Remove kit_modules and lock file
  cache                   Show cache statistics
  cache list              List cached packages
  cache clear             Clear the cache

Other:
  help                    Show this help message
  version                 Show version information

Examples:
  kit run hello.kit
  kit build hello.kit -o hello
  kit test
  kit test --coverage
  kit init my-app
  kit init my-package --package
  kit add some-package --version 1.0.0
  kit install /path/to/local-package

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

kit run

Interpret and execute a Kit file directly without compilation.

kit run <file> [--bytecode] [--allow=...] [--deny=...] [--sandbox]

Options

--bytecode - Use the experimental bytecode VM instead of the IL interpreter
--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)

Examples

# Run a Kit file
kit run hello.kit

# 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 <file> [-o <output>] [--target <target>] [--no-spinner] [--safe[=...]] [--allow=...] [--deny=...] [--sandbox]

Options

-o <output> - Specify the output file name (defaults to input file name without extension)
--target <target> - Compilation target: native (default) or wasm
--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)

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

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

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.

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	File system access
`net`	NetAuth, TCPAuth, UDPAuth, DNSAuth	Network access
`process`	ProcessAuth	Spawn external processes
`concurrency`	ActorAuth, ChannelAuth, ParallelAuth	Concurrency primitives

Fine-Grained Capabilities

For more precise control, fine-grained variants are also supported:

file-read, file-write - Read-only or write-only file access
tcp, udp, dns - Specific network protocols
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

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

For compiled binaries, capability restrictions are baked in at compile time. The binary will panic with a helpful error message if a denied capability is used.

kit repl

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

kit repl

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 [file] [--coverage] [--coverage-format=FMT] [--coverage-output=PATH]

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)

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

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.

kit task

Run tasks defined in your kit.toml file.

kit task [name] [--all]

Options

name - Run a specific task by name
--all - Run all defined tasks in sequence

Examples

# List available tasks
kit task

# Run a specific task
kit task test

# Run all tasks
kit task --all

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"]

kit check

Type check a Kit file without running or compiling it.

kit check <file> [--no-spinner]

Options

--no-spinner - Disable the progress spinner (useful for scripts and CI)

Example

$ kit check app.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 format

Format Kit source files with consistent style. Also formats Kit code blocks within Markdown files.

kit format <files...> [--check] [--indent-width <n>]

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)
--max-width <n> - Set maximum line width (default: 100)

Supported File Types

.kit - Kit source files (formats entire file)
.md - Markdown files (formats ```kit code blocks only)

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

# Format Kit code blocks in a Markdown file
kit format README.md

# Check Markdown files in CI
kit format --check docs/*.md

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. When formatting Markdown files, only ```kit fenced code blocks are processed; all other content is preserved unchanged.

kit doc

Generate HTML documentation from doc comments in a Kit file.

kit doc <file> [-o <output>]

Options

-o <output> - Specify the output HTML file

Example

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

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 lsp

Start the Language Server Protocol (LSP) server for IDE integration. The LSP server provides rich editor features like autocomplete, hover information, and diagnostics.

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
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 a simple application; use --package for a full package with manifest.

kit init [name] [--package]

Options

--package - Create a package project with kit.toml, examples/, and tests/ directories

Simple Application (default)

# Create a simple application
$ kit init my-app
Created new Kit project: my-app
  src/main.kit
  .gitignore
  .editorconfig
  .tool-versions

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

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)
kit.toml - Package manifest (only with --package)
examples/ - Example files directory (only with --package)
tests/ - Test files directory (only with --package)

kit install

Install dependencies or a local package.

kit install [/path/to/package]

When run without arguments, installs all dependencies listed in kit.toml to the kit_modules/ directory.

When given a path to a local package, installs it to ~/.kit/packages/ (with exclude patterns applied).

Examples

# Install project dependencies
kit install

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

kit add

Add a dependency to your project.

kit add <package> [--version <version>]

Examples

# Add a package
kit add json-parser

# Add with specific version
kit add json-parser --version 1.2.0

kit remove

Remove a dependency from your project.

kit remove <package>

kit clean

Remove the kit_modules/ directory and lock file.

kit clean

kit cache

Manage the package cache.

# Show cache statistics
kit cache

# List all cached packages
kit cache list

# Clear the cache
kit cache clear

Environment Variables

Variable	Description	Default
`KIT_HOME`	Kit home directory for global configuration and cache	`~/.kit`

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"

# Git dependency
my-lib = { git = "https://github.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"]