Skip to content

Command line · Kotlin Toolchain projects

kt — Kotlin from the terminal

The compile errors, the real signature of a library call, every use of a name, a rename that refuses to break the build, the tests one by one — what the editor knows, for you at a prompt and for an agent that has no editor.

# macOS, Apple silicon — the other platforms are below
$ mkdir -p ~/.local/share ~/.local/bin
$ curl -fsSL https://kotlin.optersoft.com/kt/kt-macos-arm64.tar.gz | tar -xz -C ~/.local/share
$ ln -sf ~/.local/share/kt/kt ~/.local/bin/kt
$ kt --version

Download

Each archive is one folder, kt/: the program, and the Java it compiles with your project’s JDK the first time it needs it. Keep the folder whole. The checksums of all six are in SHA256SUMS.

$ curl -fsSLO https://kotlin.optersoft.com/kt/SHA256SUMS
$ shasum -a 256 -c SHA256SUMS --ignore-missing    # Linux: sha256sum -c SHA256SUMS --ignore-missing

Install

macOS and Linux

Put your platform’s file name in the curl line. ~/.local/bin has to be on your PATH.

$ mkdir -p ~/.local/share ~/.local/bin
$ curl -fsSL https://kotlin.optersoft.com/kt/kt-linux-x64.tar.gz | tar -xz -C ~/.local/share
$ ln -sf ~/.local/share/kt/kt ~/.local/bin/kt
$ kt --version

Windows (PowerShell)

Unpacks into your user folder and adds it to your PATH; open a new terminal after.

> Invoke-WebRequest https://kotlin.optersoft.com/kt/kt-windows-x64.zip -OutFile kt.zip
> Expand-Archive kt.zip $env:LOCALAPPDATA -Force
> [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:LOCALAPPDATA\kt", "User")

Downloaded with a browser on macOS instead? The system then refuses to open it, because the file arrived marked as from the internet. Clear the mark once: xattr -dr com.apple.quarantine ~/.local/share/kt.

To update, run the same lines again. To remove it, delete the kt folder and the link.

First steps

# a project, with an AGENTS.md that tells an agent how to work in it
$ kt new jvm-cli hello && cd hello
# what is wrong, as file:line:col — the first run fetches the toolchain
$ kt check
# a dependency, at its newest release
$ kt add org.jetbrains.kotlinx:kotlinx-datetime
# the real signature and docs of what you are about to call
$ kt api kotlinx.datetime.LocalDate
# each test passed or failed, a failure at its file:line
$ kt test

kt on its own lists every command. Anything it does not know — kt build, kt run — goes to JetBrains’ kotlin unchanged.

With an agent

Instructions it can follow

kt guide prints the AGENTS.md text: which command answers which question. kt new writes it into every project it makes.

Answers it can act on

Every command takes --json. Exit 0 is done, 1 is the code is wrong, 2 is the setup is wrong — so an agent knows whether to fix the code or ask you.

As MCP tools

kt mcp serves the same commands over stdio to any MCP client: the command is kt, the argument mcp.

What it needs

JetBrains’ Kotlin Toolchain, to start a project

kt new asks it for the template. Without it, kt says so and where to get it: kotlin-toolchain.org.

Nothing more inside a project

A Kotlin Toolchain project carries its own ./kotlin, and kt uses it — the toolchain and the dependencies it pins arrive on the first kt check (on a new machine about 700 MB and half a minute, said as it happens; once).

The editor, if you want it

The same engine answers in VS Code: the Kotlin Toolchain extension carries its own copy.