Command-Line Interface
The karkain binary is the single entry point for the entire Karkain
toolchain. Every operation — compile, run, test, format, debug, profile,
package management, LSP — is exposed through subcommands of this one
executable.
$ karkain <command> [options] <file.kark>
Command set
Compiler commands
Command |
Description |
|---|---|
|
Compile and execute in one step (default when no command is given) |
|
Compile to a native executable without running |
|
Generate C23 source without compiling or linking |
|
Validate syntax and semantics (no binary produced) |
|
Discover and run |
|
Time |
|
Compile, run, and profile with per-function instrumentation |
|
Full front-end analysis including borrow checker |
|
Explain a toolchain error code ( |
Tool commands
Command |
Description |
|---|---|
|
Canonicalize formatting ( |
|
Remove generated artifacts (sources never touched) |
|
List the host triple and all supported |
|
Print the effective toolchain configuration |
IDE commands
Command |
Description |
|---|---|
|
Start the Language Server Protocol server (JSON-RPC 2.0 over stdio) |
|
Alias for |
|
Print machine-readable IDE/toolchain contract (JSON) |
Workspace commands
Command |
Description |
|---|---|
|
List members in dependency order |
|
Build all members (dependency order) |
|
Test all members |
|
Validate all members (no binaries produced) |
|
Build and run all member entrypoints |
|
Clean generated artifacts from all members |
|
Full front-end analysis of all members |
|
Show member dependency graph |
|
Initialize workspace root |
|
Add member package |
|
Remove member package |
Package commands
Top-level shortcuts and the full karkain pkg namespace are
implemented. See Packages for the complete reference.
$ karkain init [name] # create new project
$ karkain new <name> # create a new project directory
$ karkain add <pkg> [version] # add dependency
$ karkain remove <pkg> # remove dependency
$ karkain fetch # fetch resolved dependencies (lockfile)
$ karkain update [pkg] # re-resolve versions, write karkain.lock
$ karkain list # list direct + transitive dependencies
$ karkain tree # show recursive dependency graph
These are equivalent to the karkain pkg <verb> spellings.
Options
Option |
Arg |
Description |
|---|---|---|
|
yes |
Output binary path ( |
|
no |
Emit C source but do not invoke gcc/clang |
|
no |
Generate debug symbols and |
|
yes |
Target architecture for |
|
yes |
Run only matching tests (substring of test name) |
|
no |
Emit detailed pipeline logs |
|
yes |
Select the compiler engine (default |
|
no |
Show version |
|
no |
Show help |
Engine selection
Karkain has two compiler engines:
kcc — the self-hosted compiler, bootstrapped from
src/compiler/*.kark. This is the default engine.go — the in-tree Go front end (
pkg/lexer+pkg/parser+pkg/codegen).
The engine is selected by (in order of priority):
The
--engineflag on the command line.The
KARKAIN_ENGINEenvironment variable (go/Go/GOselects the Go front end; any other value or an empty value selectskcc).Default:
kcc.
$ karkain run --engine go hello.kark # force Go engine
$ KARKAIN_ENGINE=go karkain run hello.kark # same via env var
Note
Some commands (prof, debug) are Go-engine-only in the current
release and explicitly refuse the kcc engine with an error — there
is no silent fallback.
Exit codes
Code |
Name |
Meaning |
|---|---|---|
|
|
Command completed successfully |
|
|
General or program failure (runtime error, assertion, non-zero program exit, missing/invalid profile dump) |
|
|
CLI usage error (unknown flag or command, missing argument, invalid target or extension) |
|
|
Lexer, parser, semantic, type, borrow, or codegen failure |
|
|
One or more tests failed |
|
|
Package or dependency failure |
|
|
Infrastructure or toolchain failure (no usable C compiler, missing cross-linker) |
|
|
Lint-specific failure (warnings treated as errors) |
Version
$ karkain -v
Karkain Compiler v1.1.0 (linux/amd64, Stable Build)
The version string reports the toolchain version, host OS and host architecture.