Installation

Kona uses two command-line tools on purpose:

Tool	Where it lives	What it does
kona	On your PATH (global)	Creates apps (kona new) and can proxy to grind (kona grind …)
./grind	Inside each app created by kona new	Day-to-day work for that app: serve, generate controllers, …

You install kona once. Every project from kona new ships its own ./grind (and grind.bat on Windows). Prefer ./grind when you are already in the app directory; from a nested folder (or out of habit) you can also run kona grind <command> — it walks upward for a Gradle project and forwards the rest of the line to that app’s grind script.

Happy path

# 1. JDK 21+ on your PATH
java -version

# 2. Install the global `kona` CLI (fetches source, builds, links ~/.local/bin/kona)
curl -fsSL https://raw.githubusercontent.com/konaframework/kona/main/scripts/install.sh | bash

# 3. Create an application
kona new my-app
cd my-app

# 4. Serve with the app-local CLI (or: kona grind serve)
./grind serve

Open http://127.0.0.1:4000/. That is the supported path: install kona → kona new → ./grind serve (equivalently kona grind serve from inside the app tree).

1. JDK 21+

java -version   # must report 21 or newer

The installer and generated apps use the Gradle wrapper; you do not need a separate Gradle install.

2. Install the global kona CLI

Recommended: curl installer

curl -fsSL https://raw.githubusercontent.com/konaframework/kona/main/scripts/install.sh | bash

That script prints a colored step progress (JDK → fetch → build CLI → publish libraries → publish sister packages → link), syncs source into ~/.kona (override with KONA_SRC), builds :kona-cli:installDist, publishes all core org.konaframework jars to ~/.m2 (mavenLocal), then publishes sister packages kona-brew / kona-inertia when a checkout is found (sibling dirs, KONA_BREW_SRC / KONA_INERTIA_SRC, or clones under ~/.kona-brew / ~/.kona-inertia). It installs under ~/.local/lib/kona with a symlink at ~/.local/bin/kona (override prefix with KONA_PREFIX), records the checkout path in ~/.config/kona/home so kona new can set kona.home on new apps (includeBuild), and removes obsolete vendored modules/brew / modules/inertia trees that would poison that composite build. Set NO_COLOR=1 to disable ANSI styling.

Why publish?

Generated apps depend on org.konaframework:…:0.1.0-SNAPSHOT from mavenLocal() / Maven Central. Those SNAPSHOT jars are not on Central yet — the installer must publish them locally so ./grind serve can resolve transitive modules such as kona-filesystem and kona-support.

Ensure ~/.local/bin is on your PATH, then check:

kona version
kona help

Re-run the same curl command (or ~/.kona/scripts/install.sh) to update.

Variable	Default	Meaning
KONA_SRC	~/.kona	Where source is cloned / updated
KONA_PREFIX	~/.local	Where bin/kona and lib/kona are installed
KONA_REF	main	Git branch or tag to install
KONA_REPO	https://github.com/konaframework/kona.git	Clone URL
KONA_BREW_SRC	sibling ../kona-brew or ~/.kona-brew	Optional Brew checkout to publish
KONA_INERTIA_SRC	sibling ../kona-inertia or ~/.kona-inertia	Optional Inertia checkout to publish

Example — install a specific ref into a custom prefix:

KONA_REF=main KONA_PREFIX=$HOME/.local \
  curl -fsSL https://raw.githubusercontent.com/konaframework/kona/main/scripts/install.sh | bash

What about package managers?

Homebrew, SDKMAN, and standalone GitHub Release binaries are not published yet. The curl installer is the supported path. Framework libraries still publish under the org.konaframework Maven group for applications to depend on — that is separate from putting the kona CLI on your PATH.

Framework contributors (local checkout)

If you already have the repository cloned and are hacking on Kona itself:

./scripts/install-kona.sh

git clone https://github.com/konaframework/kona.git
cd kona
./scripts/install.sh --local

--local builds from that tree and does not fetch into ~/.kona.

3. Create an application

kona new my-app                 # Kotlin (default)
kona new my-app --lang=java

kona new writes a self-contained Gradle app that already includes:

• ./grind / grind.bat — app-local CLI
• ./gradlew / gradlew.bat — Gradle wrapper
• src/main/… layout, .env, and starter kit files

You should see a hint ending with ./grind serve.

4. Work inside the app with ./grind

cd my-app
./grind serve
./grind make:controller Post

./grind is a thin script that runs the project’s Gradle grind task with kona-grind on the classpath. It is not the same binary as global kona, and it is not something you copy from the Kona monorepo by hand.

Trying the repo samples

The checked-in apps under samples/hello-kotlin and samples/hello-java are monorepo Gradle modules used for regression and layout reference. They intentionally:

• do not ship ./grind or their own ./gradlew
• depend on sibling project(":kona-…") modules instead of Maven coordinates
• are run from the Kona repository root

# from the Kona checkout root
./gradlew :hello-kotlin:run
./gradlew :hello-java:run

To experience the product path (./grind serve, generators, a standalone wrapper), use kona new as above. Do not expect ./grind inside samples/ — those directories are not full scaffolds.

Optional: local Kona sources while developing the framework

Generated apps depend on org.konaframework:kona-http, org.konaframework:kona-grind, and related artifacts from mavenLocal() / Maven Central. If you are changing Kona itself:

# from the Kona checkout
./gradlew :kona-core:publishToMavenLocal :kona-http:publishToMavenLocal :kona-grind:publishToMavenLocal

Or point the app at a checkout:

./gradlew run -Pkona.home=/path/to/kona
# or: export KONA_HOME=/path/to/kona

You do not need these steps just to try Kona after a normal kona new.

Next

• Your first app — walk through what kona new creates
• grind — app-local commands in detail