1. Install Kobalt


Download the zip file, unzip it and add the bin directory to your $PATH variable so that you can invoke the command kobaltw:

cd yourLocation
unzip kobalt-xxx.zip
cd kobalt-xxx
export PATH=$PWD/bin:$PATH

With HomeBrew

If you are on MacOS and have brew installed:

$ brew install kobalt
$ which kobaltw

Note that the Kobalt version on Homebrew might be a bit behind, but once installed, you can easily upgrade to the latest version with kobaltw --update.

2. Initialize your project

Change to your project directory and call the kobaltw command with --init:

cd ~/java/project
kobaltw --init java
to initialize a Java project, or
cd ~/java/project
kobaltw --init kotlin

to initialize a Kotlin project.


Kobalt supports projects with both Kotlin and Java sources. For such projects, use either java or kotlin as the --init argument and refer to the mixed projects documentation for more details.

This command will do two things:

  1. Create a default kobalt/src/Build.kt file based on what was found in your project.
  2. Install the Kobalt Wrapper in your current directory (a script called kobaltw) and a few additional files in the kobalt/wrapper directory.

From now on, you can just use ./kobaltw to build and you can ignore the kobaltw on your path, which is only useful to install Kobalt on new projects. Since you will now build each project with its own ./kobaltw command, they will use their own version of Kobalt.

3. Edit kobalt/src/Build.kt

If your project uses a standard folder structure, you can skip this section and try to build your project directly.

The build file generated by default might need some editing before you can build your project, so take a look at it and adjust whatever is necessary (e.g. package name, version, etc...)

Here is the Build.kt for the JCommander project:

import com.beust.kobalt.*
import com.beust.kobalt.plugin.java.*
import com.beust.kobalt.plugin.packaging.*
import com.beust.kobalt.plugin.publish.*

val jcommander = project {
    name = "jcommander"
    group = "com.beust"
    artifactId = name
    version = "1.54"

    dependenciesTest {

    assemble {
        mavenJars {

    jcenter {
        publish = true

4. Build your project

You can now attempt to build your project with Kobalt:

./kobaltw assemble

5. IDEA users: Import your project in IDEA

You can now open your project in IDEA and if you have the Kobalt IDEA plug-in installed, you will be asked whether you want to import that project as a Kobalt project.

6. IDEA users: Sync your build file

Once your project has been imported as a Kobalt project in IDEA, bring up the Kobalt window (sideways on the right side) and click the Sync icon, which will synchronize your build file with IDEA.

7. Next steps

From this point, you can either learn how to install the Kobalt IDEA plug-in or read Kobalt's documentation.