Skip to main content

Configuration

scala-cli can be configured in two ways:

  • on the command-line
  • directly in .scala and .sc files

Parameters on the command line take precedence over parameters in sources. That way, you can quickly override parameters from the command line.

danger

The configuration options and syntax in .scala (and .sc) files is likely to evolve in the future.

Command-line​

Pass --help to any sub-command of scala-cli to list its options:

scala-cli --help
scala-cli package --help

As an example of command line configuration, one thing you can do with scala-cli command line options is to specify the Scala version:

scala-cli --scala 3.0.0 Test.scala

Another thing you can do is to specify dependencies:

scala-cli --dependency org.typelevel::cats-core:2.3.0 Test.scala

The reference documentation lists all of the available options.

In .scala and .sc files​

Configuration information can also be put in .scala and .sc files using special imports, and the using directive.

Using directives​

Scala CLI can be configured inside .scala files. This is achieved by specifying using directives inside comments at the top of a .scala file, before any package or import statement:

//> using scala "2.13"
//> using platform "scala-js"
//> using options "-Xasync"

// package and import statements follow here ...

The reference documentation lists all available using directives.

Special imports​

Dependencies can be added right from .scala and .sc files, using the same syntax as Ammonite and Metals worksheets:

import $dep.`com.lihaoyi::upickle:1.4.0`
import $ivy.`com.lihaoyi::pprint:0.6.6`
import ujson._

Both import $ivy and import $dep are accepted, and are equivalent. Note that this syntax might be deprecated - and then removed - in the future. It's recommended to add dependencies with using directives.