Kotlin Tooling Kotlin Toolchain

Kotlin Toolchain

JetBrains' unified CLI for Kotlin (JVM, Android, iOS, multiplatform) and Java projects, in Alpha. Configuration is declarative YAML instead of Gradle build scripts.

Installation

Prefer the project's checked-in wrapper: ./kotlin build needs nothing installed — the wrapper downloads the CLI itself. Install a global CLI only when there is no wrapper (e.g. before kotlin init):

sdk install kotlintoolchain      # SDKMAN (macOS / Linux / WSL)

The kotlin command then auto-provisions its JDK on first use. Other install options (installer scripts, IntelliJ IDEA plugin) live at https://kotlin-toolchain.org/.

If the project root ships wrapper scripts (kotlin / kotlin.bat), the global kotlin detects them and proxies into them, pinning the project to the wrapper's version. Always invoke kotlin from the project root so the wrapper wins; never call a globally installed binary directly when a wrapper exists.

CLI commands

For the detailed list of commands and their options, run kotlin --help or kotlin <command> --help.

Project structure

project-root/
├── kotlin, kotlin.bat     # Local wrappers
├── project.yaml           # Project-level config
├── libs.versions.toml     # Version catalog (Gradle-compatible; root or gradle/)
├── module-name/
│   ├── module.yaml        # Module configuration
│   ├── src/               # Production sources (Kotlin + Java mixed when JVM platform is available)
│   ├── resources/         # Resources (copied into JAR)
│   ├── test/              # Test sources
│   └── testResources/     # Test-only resources
└── another-module/
    ├── module.yaml
    └── ...

project.yaml declares the project's modules and any local build plugins. See references/examples.md for a project-level config example.

module.yaml

product: jvm/app    # jvm/app, jvm/lib, android/app, lib (multiplatform), …

dependencies:
  - org.example:artifact:1.0.0           # Maven coordinates
  - //other-module                       # Module dependency (relative path from the project root)
  - $libs.ktor.client                    # From version catalog
  - bom: io.ktor:ktor-bom:2.2.0          # BOM import
  - org.example:foo:1.0.0: exported      # Exposed to dependents (like Gradle api())
  - org.example:bar:1.0.0: compile-only
  - org.example:baz:1.0.0: runtime-only

test-dependencies:
  - io.mockk:mockk:1.13.0

settings:
  jvm:
    mainClass: org.example.MainKt   # Default: main() in main.kt
    jdk:
      version: 21
  kotlin:
    languageVersion: 2.0
  compose:
    enabled: true

test-settings:
  kotlin:
    languageVersion: 2.0

Notes:

• module.yaml does not support ${...} interpolation. Values are literal strings/booleans/numbers; paths are relative to the module root. Interpolation works only in plugin.yaml.
• The module name is the basename of the directory holding module.yaml. There is no name: field.
• Tests use kotlin.test by default, no dependency needed.

Version catalogs use the standard Gradle libs.versions.toml format, referenced as $libs.<key>. Built-in catalogs $kotlin.* and $compose.* derive their versions from settings.

Templates

A template extracts reusable module.yaml sections into a <name>.module-template.yaml file (same structure as module.yaml) that modules pull in via an apply: list of relative paths. It's a general reuse mechanism — sharing project-wide config is just one use. There is no enforced convention for where the file lives. Modules reference it by path under apply:.

Because there is no project-wide settings: block, templates are the only way to share configuration (Kotlin language version, common test dependencies, repositories, …) across modules. apply: one template everywhere for project-wide defaults, or keep several templates and apply different combinations to different subsets of modules — e.g. a common template in every module plus a service-only template in the backend modules. A module can list multiple templates under apply:.

# common.module-template.yaml
test-dependencies:
  - io.mockk:mockk:1.13.0
settings:
  kotlin:
    languageVersion: 2.0

# module.yaml
product: jvm/app
apply:
  - //common.module-template.yaml
  - //jvm-service.module-template.yaml

• Templates can't have product: or apply: sections — a template can't apply another template (no recursion) and can't define products.
• Applied one by one, with module.yaml's own values last: scalars are overridden, lists and mappings appended, and module.yaml always wins regardless of apply: position.

Checks and linters

kotlin check runs all tests plus every registered check. Filter by name (kotlin check detekt apiCheck), skip with --skip <name> (e.g. --skip tests), restrict to modules with -m <module> (repeatable), and list what exists with kotlin show checks. A check fails when its underlying task throws.

The Toolchain ships no bundled linters — tests is the only built-in check. detekt, ktlint, and API-compatibility verification must be registered as local-plugin tasks under checks: in plugin.yaml.

Multiplatform

Platform code lives in @platform-suffixed directories: src@jvm/, src@ios/, src@android/. Common code in src/ is visible to platform directories, not the reverse. Dependencies and settings take the same qualifier:

dependencies@android:
  - androidx.core:core-ktx:1.12.0

iOS apps

For an ios/app module the Toolchain generates and manages the Xcode project. On first build, if no Xcode project exists, it creates module.xcodeproj (target app), writes a complete default Info.plist, points INFOPLIST_FILE at it, and uses it verbatim — it does not enable GENERATE_INFOPLIST_FILE.

• A pre-existing Info.plist is used as-is and never completed. It must itself carry the required CFBundle* keys (CFBundleIdentifier, CFBundleExecutable, CFBundleName, …). A partial plist yields an .app with no bundle id and the simulator refuses it:

  Simulator device failed to install the application. Missing bundle ID.

• kotlin init iOS apps never hit this; migrated projects with their own Info.plist do. See the kotlin-tooling-gradle-to-kotlin-toolchain-project skill for the Gradle/KMP case.

• module.xcodeproj is created only when absent and is not regenerated when module.yaml changes. Delete it to force regeneration.