Skip to content

Kotlin CLI

The Kotlin CLI is a command-line tool to build, run, test, and package your project without an IDE. It is useful both locally and in CI/CD pipelines.

Installation

To use the Kotlin CLI, you need to download the Kotlin wrapper script.

It is recommended to place it in your project root and check it into your VCS, so your team can build and run your project without any installation, no matter their OS.

IntelliJ IDEA can take care of this for you

New projects created using the IntelliJ IDEA wizard will already contain the wrapper scripts. Also, if you create a module.yaml file in a blank project, IntelliJ IDEA will offer to setup the wrapper scripts for you.

Use the following command in your project directory to download the script and set up the Kotlin Toolchain:

curl -fsSL -o amper https://jb.gg/amper/wrapper.sh && chmod +x amper && ./amper update -c
PowerShell
Invoke-WebRequest -OutFile amper.bat -Uri https://jb.gg/amper/wrapper.bat; ./amper update -c
cmd.exe
curl -fsSL -o amper.bat https://jb.gg/amper/wrapper.bat && call amper update -c

The ./amper update -c command following the download is not strictly necessary, but it will automatically get the wrapper script for the other OS. It is good practice to check them both into your VCS so your team can build and run your project without any installation, on any OS.

Note

The first time you run the Kotlin wrapper script, it will take some time to download the Kotlin CLI distribution. Subsequent runs will be faster, as the downloaded files will be cached locally.

The ./amper update call that is part of the above installation command will actually do this first run for you.

Exploring Kotlin CLI commands

The root ./amper command and all subcommands support the -h (or --help) option to explore what is possible:

./amper --help       # shows the available commands and general options
./amper build --help # shows the options for the 'build' command specifically

Useful commands:

  • amper init to create a new Kotlin project
  • amper build to compile and link all code in the project
  • amper run to run your application
  • amper test to run tests in the project
  • amper show (modules|settings|dependencies|tasks) to introspect the project's configuration
  • amper clean to remove the project's build output and caches

Try it out!

Create a new project using the ./amper init command and select the JVM console application template.

Then build and run the application using ./amper run.

Tab-completion

If you’re using bash, zsh, or fish, you can generate a completion script to source as part of your shell’s configuration, to get tab completion for Kotlin CLI commands.

First, generate the completion script using the generate-completion command, specifying the shell you use:

./amper generate-completion bash > ~/amper-completion.sh

./amper generate-completion zsh > ~/amper-completion.sh

./amper generate-completion fish > ~/amper-completion.sh

Then load the script in your shell (this can be added to .bashrc, .zshrc, or similar configuration files to load it automatically):

source ~/amper-completion.sh

You should now have tab completion available for Kotlin CLI subcommands, options, and option values.

Updating the Kotlin Toolchain to a newer version

Run ./amper update to update the Kotlin CLI scripts and the toolchain distribution to the latest released version. Use the --dev option if you want to try the bleeding edge dev build of the Kotlin Toolchain (no guarantees are made on these builds).

See ./amper update -h for more information about the available options.

Don't forget to regenerate your tab-completion script, if you have one.