SIP-46 - Scala CLI as default Scala command

SIP-46 has been accepted and now is in the implementation phase. Its intention is to enhance the default scala runner with a larger number of features using scala-cli. This doesn’t mean that all Scala CLI features will be available in the default Scala runner, but the main ones and the overall UX will be included. Some features might be introduced later on within additional SIP.

Additionally, in order to replace it we need to make it as compatible with the older Scala runner as possible. The main compiler options should be available to use (with some required to be passed with -O). More details here.

There are currently two ways of installing the experimental version of scala runner:

  • with brew:

brew install virtuslab/scala-experimental/scala

  • with coursier:

cs setup

cs install scala-experimental ← this command will replace the default scala runner

Quick overview of current features can be found at scala-cli website

Please let us know if you have any questions or issues. We would be happy to try and improve anything related to setup or features of ScalaCLI as Scala.


This doesn’t mean that all Scala CLI features will be available in the default Scala runner

Can you say a little bit more about this? I thought the idea was that scala-cli would be scala and we wouldn’t have to keep telling people to install something else.

1 Like

The choice was to proceed step by step, so that we can have a clear spec for all commands that get added in.

You can read about it in the Specification paragraph of the accepted proposal SIP-46 - Scala CLI as default Scala command | Scala Documentation

The general idea is that the new scala command will initially support a subset of features from scala-cli that more or less map to the current scala command. Those are the MUST features in the proposal.
scala-cli (which will get installed together with scala) will support all of the features.

As those features stabilize, they will gradually move into the main scala binary via additional SIPs.

Correct me if I’m wrong @romanowski @tgodzik or @bjornregnell


I think it’s a bit different: The SIP specced features that a scala runner must have, and it will stop there. So it specced a minimum functionality of a runner, but not the precise functionality. The scala command is free to support other features as well. No SIP will be needed for these, unless we want to postulate that they will also have to be in any future runner we might think of.

So from that perspective I see no impediment to simply rename scala-cli to scala. There might be another impediment though that I have overlooked here.


I probably worded it poorly.

I was referring to this part of the SIP that got approved:

In order to be able to expand the functionality of Scala CLI and yet use the same core to power the scala command, we propose to include both scala and scala-cli commands in the installation package. Scala CLI already has a feature to limit accessible sub-commands based the binary name (all sub-commands in scala-cli , and a curated list in scala ). On later date, more features from scala-cli could be included into scala command by additional SIPs or similar processes.

Whether we need a SIP or not to “enable” more commands in the main scala runner is probably not as clear cut as I implied. It could probably be a less formal process.

I am a bit worried that introducing a new script named scala while still recommending / distributing other scala scripts will cause confusion. I think we should have a plan / discussion about what happens to the download / installation page and how the introduction of scala-cli as scala affects building releases / distributions / other packages.

It’s fine to share it with contributors early, though IMO it wouldn’t be too hard for contributors to create an alias or symlink for the moment.


This is a temporary solution only to allow the community to test it and give us feedback. After the SIP Committee decides to make it “stable”, we will update the official Scala distribution to use that scala command.


I have an issue with install-completions. It works with scala-cli install-completions but not with the new scala after scala install-completions after installing the new scala with cs install scala-experimental. The scala help text says it should work and the text about source bashrc comes up so it seems as if scala thinks it has installed completions but actually no completions work…

$ scala uninstall-completions
Problem occurred while uninstalling scala-cli completions
Updated /home/bjornr/.bashrc
scala-cli completions uninstalled successfully
$ scala install-completions
Updated /home/bjornr/.bashrc
It is recommended to reload your shell, or source /home/bjornr/.bashrc in the current session, for its changes to be taken into account.
$ scala set<TAB> #nothing happens
$ tail ~/.bashrc 
# <<< scala-cli completions <<<

# >>> .scala.aux completions >>>
_.scala.aux_completions() {
  local IFS=$'\n'
  eval "$(.scala.aux complete bash-v1 "$(( $COMP_CWORD + 1 ))" "${COMP_WORDS[@]}")"

complete -F _.scala.aux_completions .scala.aux
# <<< .scala.aux completions <<<

What about doing what it says:

$ . ~/.bashrc
$ scala set<TAB>

It seems to work for me correctly from bash after reloading it. Could you try again @bjornregnell ?

Interestingly enough I get:

# >>> scala completions >>>
_scala_completions() {
  local IFS=$'\n'
  eval "$(scala complete bash-v1 "$(( $COMP_CWORD + 1 ))" "${COMP_WORDS[@]}")"

complete -F _scala_completions scala
# <<< scala completions <<<

So maybe .scala.aux is the issue?

Btw. currently the best reference of what scala-experimental can do might be found at Commands | Scala CLI since it list everything in a much more compact matter. I haven’t previously linked to that directly.

I’ve tried to use the new scala command to run an old script I have that used to work with Scala 2.13.

I noticed the following compatibility issues:

  • the shebang header is different. It now has to be the following:

    #!/usr/bin/env scala -S shebang

    I wonder if it would be possible to remove the shebang command at all (like in the Scala 2 runner)? Otherwise, there should be a good documentation explaining how to migrate from the Scala 2 runner. I wonder if this issue is related to that as well.

  • self-executable scripts without extension are not supported. You have to add either the .sc or .scala extension. When I looked at that, I noticed that the file extensions have different meanings for Scala CLI (ie, .sc files are interpreted as a “worksheet” whereas .scala files are interpreted as regular Scala program— ie, with a “main” method). It seems that the Scala 2 runner supports both use cases regardless of the file extension: if a standard main method is detected, that method is called, otherwise we fallback to the “worksheet” mode (which is similar to the .sc mode of Scala CLI). There is an open issue related to that (but there is no discussion about the differences between .sc and .scala scripts).

  • the -save option is not supported anymore. My understanding is that Scala CLI now always behaves like the Scala 2 runner with the -save option. I would suggest recognizing it but showing a warning like “Unnecessary option: -save. This option is always enabled.”