scala-cli

Start a REPL (interactive shell) using a specific Scala and JVM version

$ scala-cli --scala [3.1.0] --jvm [temurin:17]

$ scala-cli run [path/to/script.scala]

$ scala-cli test [path/to/script.scala]

$ scala-cli fmt [path/to/script.scala]

$ scala-cli setup-ide [path/to/script.scala]

scala-cli [options] [subcommand] [subcommand-options] [arguments...]

Common usage examples:

scala-cli run MyScript.scala [--] [script-arguments...]
scala-cli compile .
scala-cli test .
scala-cli repl
scala-cli package . -o my-app

run [sources...]
    Executes Scala source files or a compiled application. Often used for scripting and direct execution.

compile [sources...]
    Compiles Scala source files into JVM bytecode.

test [sources...]
    Discovers and runs tests defined in your project or source files.

repl
    Starts an interactive Scala REPL (Read-Eval-Print Loop) with configured dependencies.

package [sources...]
    Packages the application into various formats, such as JAR, native executable (via GraalVM), or other distributions.

setup
    Helps install or configure necessary components like Bloop, Coursier, or the CLI itself.

clean
    Removes temporary build files and caches generated by scala-cli.

config
    Manages configuration options for scala-cli.

export
    Exports a scala-cli project to a build tool definition (e.g., sbt, Mill, Scala.js).

--version
    Displays the installed version of scala-cli.

--power
    Enables experimental and potentially unstable 'power' features, offering advanced control.

--help, -h
    Shows help information for the main command or a specific subcommand.

scala-cli is a modern, feature-rich command-line interface for Scala development, designed to simplify common tasks like running scripts, compiling code, managing dependencies, and packaging applications. It aims to provide a fast and user-friendly experience, making it easier to get started with Scala, particularly for scripting and small to medium-sized projects.

It acts as a powerful orchestrator, capable of running single Scala files, entire directories, or even mixed Scala/Java sources. It intelligently resolves dependencies, integrates with bloop for fast incremental compilation, and offers features like testing, packaging native executables (via GraalVM), and creating project definitions. It can be seen as a successor to the traditional scala runner, providing a more robust and complete development environment out of the box, suitable for both beginners and experienced Scala developers.

Dependency resolution can sometimes incur a noticeable delay on the first run due to downloading artifacts. While scala-cli simplifies many aspects, large, complex multi-module projects might still find more established build tools like sbt or Mill more suitable for highly customized or intricate build logic. Features enabled via --power are experimental and subject to change or removal in future versions.

scala-cli files can be made executable scripts using a shebang line like #!/usr/bin/env scala-cli. This allows them to be run directly from the shell like any other script without explicit invocation via 'scala-cli run'.

Source files can include special //> using directives to specify dependencies, Scala versions, JVM options, and other project configurations directly within the source code. This eliminates the need for separate build files for simple projects, simplifying setup and making scripts self-contained.

scala-cli integrates with and can generate project files for other established Scala build tools like sbt, Mill, and more. This offers flexibility for projects that might start as simple scripts but eventually require the robust features of a full-fledged build system.

scala-cli emerged as a successor and modern alternative to the aging scala command-line runner. It was developed by VirtusLab and later became a part of the Scala organization's official tooling, aiming to provide a more integrated, faster, and user-friendly experience for Scala developers. Its development was driven by the desire to improve the 'getting started' experience with Scala, streamline common development workflows, and leverage modern build infrastructure like Bloop for fast incremental compilation, addressing long-standing pain points in the Scala ecosystem. It quickly became the recommended command-line tool for scripting and lightweight project management in Scala.

scala(1), scalac(1), sbt(1), mill(1), java(1), coursier(1)