CLI

Active contributors: Dmitriy Novozhilov, Sergej Jaskiewicz, Alexander Udalov

compiler/cli/ is the entry point for the kotlinc command line. Argument parsing, mode dispatch, and the main loop all live here. The CLI is the canonical way to invoke the compiler outside of a build tool — everything else (KGP, Maven plugin, Build Tools API) ultimately ends up calling into the same code paths.

Purpose

Provide command-line front ends for each Kotlin target (JVM, JS, native, metadata, klib) and the bookkeeping needed to run a compilation: argument parsing, configuration construction, plugin discovery, and result reporting.

Directory layout

compiler/cli/
├── bin/                       Distribution scripts (kotlinc, kotlinc.bat, ...)
├── cli-base/                  Shared base classes: arg parsing, configs, error reporting
├── cli-common/ (under cli-base/cli-common/)  Common helpers
├── cli-runner/                Class loader / preloader entrypoint
├── cli-jvm/                   kotlinc-jvm
├── cli-js/                    kotlinc-js (also used for Wasm)
├── cli-jklib/                 jklib (experimental klib variant)
├── cli-native-klib/           kotlinc-native-klib (build a Native klib)
├── cli-metadata/              kotlinc-metadata (compile a metadata module)
├── cli-arguments-generator/   Generator for argument data classes
├── resources/                 Help text, message bundles
└── src/                       Cross-cutting CLI code

The bin/ subdirectory ships shell scripts for end users (kotlinc, kotlinc-jvm, kotlinc-js, kotlinc-native, ...). They invoke the JAR built from this module via cli-runner/.

Key abstractions

Type	Where	Role
CLITool	compiler/cli/cli-base/.../CLITool.kt	Base class for all kotlinc-* entry points.
K2JVMCompiler	compiler/cli/cli-jvm/.../K2JVMCompiler.kt	The JVM CLI entry.
K2JSCompiler	compiler/cli/cli-js/.../K2JSCompiler.kt	The JS CLI entry.
K2MetadataCompiler	compiler/cli/cli-metadata/.../K2MetadataCompiler.kt	Builds a metadata-only module.
K2NativeKlibCompiler	compiler/cli/cli-native-klib/...	Builds a Native klib.
KotlinCompilerArguments	compiler/arguments/...	Strongly typed compiler arguments.
CompilerConfiguration	compiler/config/.../CompilerConfiguration.kt	The central key-value bag of compiler options.
Disposable, Disposer (IntelliJ)	from intellij-core	Lifecycle management (PSI / project disposal).

Argument layer

Compiler argument names, types, defaults, and help text are defined in compiler/arguments/. There is a single source of truth (compiler-arguments.json plus per-platform Kotlin descriptions like JvmCompilerArguments.kt) from which several outputs are generated:

• The Kotlin data classes used at runtime (compiler/arguments/src/...).
• BTAPI-facing impls (compiler/build-tools/kotlin-build-tools-impl/gen/.../*ArgumentsImpl.kt) — heavily churning files in the recent history.
• Help text and shell completion.

Adding a new compiler flag means editing the description, regenerating, and updating both the CLI parser and the BTAPI implementation.

How a compile runs

graph LR
    User["kotlinc Foo.kt"] --> Script["bin/kotlinc"]
    Script --> Runner["cli-runner main"]
    Runner --> Tool["K2JVMCompiler"]
    Tool --> Args["Argument parsing<br/>(compiler/arguments)"]
    Args --> Config["CompilerConfiguration"]
    Config --> Front["Frontend (FIR / K1)"]
    Front --> Back["Backend (JVM / JS / Wasm / Native)"]
    Back --> Out["Class files / .js / .wasm / binary"]

cli-runner/ exists because the compiler depends on intellij-core, which is a large set of classes. The runner uses a "preloader" classloader (compiler/preloader/) that warms the JVM and avoids re-parsing class definitions across multiple compilations in the same JVM.

Daemon mode

When invoked through KGP or via kotlinc --daemon, the CLI runs inside the Kotlin Compile Daemon (compiler/daemon/). The daemon hosts a long-running JVM that accepts compile requests over a local RPC channel, avoiding JVM startup costs. See daemon.md.

Help and version

kotlinc -version, kotlinc -help, and kotlinc -X print version info, common arguments, and "extended" (experimental) arguments respectively. Help text is generated from the same argument descriptions used at compile time.

Integration points

• Producers: compiler/build-tools/kotlin-build-tools-impl/ invokes the CLI shape in-process via the Build Tools API.
• Producers: KGP's KotlinCompile Gradle task uses BTAPI (or, in older versions, calls the CLI directly).
• Producers: libraries/kotlin-maven-plugin/ invokes the CLI in-process.
• Producers: JPS uses compiler/incremental-compilation-impl/ which reuses CLI argument parsing.

Where to start

To add a new compiler flag, start in compiler/arguments/. To change the JVM compile flow, compiler/cli/cli-jvm/.../K2JVMCompiler.kt. To change argument processing across all CLIs, the base classes in compiler/cli/cli-base/.

See build-tools.md for the API around the CLI and daemon.md for the long-running compile process.