# Using ScalaCLI with IntelliJ IDEA

> **TL;DR**
> Required plugin: Scala: [how to install](get-started-with-scala.html#scala_plugin)

ScalaCLI is a command-line tool designed to simplify the process of working with Scala code. ScalaCLI is not intended to replace full-fledged build tools like sbt or Mill but is well-suited for simpler projects and tasks where a lightweight, easy-to-use tool is beneficial. It is particularly useful for single-module projects, such as terminal-based applications, basic web applications, or serverless lambdas, as well as for scripting, and to quickly prototype ideas without the overhead of more complex build tools.

## Setting up ScalaCLI

To set up ScalaCLI on your computer, visit the [ScalaCLI
website](https://scala-cli.virtuslab.org/install) and follow the instructions.

After installation, verify that ScalaCLI is working by running: `scala-cli --version`

> **Note:**
> Since Scala 3.5.0, Scala CLI is the default Scala runner, so there is no need to install ScalaCLI separately. The installed `scala` command will use`scala-cli` under the hood.

## Create a new ScalaCLI project

Procedure:

1. In IntelliJ IDEA, select `File | New Project...`

2. In the New Project wizard, choose ScalaCLI as your build system.

3. Decide what Scala version and what syntax you want to use.

4. Click Create.

![Creating a new ScalaCLI project](https://resources.jetbrains.com/help/img/idea/2026.2/scalacli_newproject.png)

## Import a new ScalaCLI project

Procedure:

1. Open a terminal and navigate to the directory where you want to create your project.

2. Run the following command to create a new ScalaCLI project: `scala-cli new project-name`. This will create a new directory with the basic structure of a ScalaCLI project.

3. In IntelliJ IDEA, select `File | New | Project from Existing Sources...`

4. Select the directory of your new ScalaCLI project.

5. Choose BSP as the external model. If BSP doesn't show up, generate the .bsp folder using `the scala-cli setup-ide .` command in your project directory.

![Importing a new ScalaCLI project](https://resources.jetbrains.com/help/img/idea/2026.2/scalacli_import.png)

Once the project is imported, IntelliJ IDEA will use Scala CLI's BSP command to handle running, testing, and debugging your code. You can manage your project structure through the command line, and changes will be reflected in IntelliJ IDEA.

## Importing an existing ScalaCLI project

Procedure:

1. In IntelliJ IDEA, select `File | Open`.

2. Select the directory of your new ScalaCLI project.

3. Choose BSP as the external model. If BSP doesn't show up, generate the .bsp folder using the `scala-cli setup-ide .` command in your project directory.

## Working with ScalaCLI

In simple one-file scripts, ScalaCLI directives can be put at the top of the file. In larger projects, the directives are usually put in project.scala. When you import a ScalaCLI project into IntelliJ IDEA, or when you use the scala-cli setup-ide . command, a BSP configuration file is being generated (`.bsp/scala-cli.json`). IntelliJ IDEA uses this BSP configuration to import the project. This allows IntelliJ IDEA to understand the project structure and dependencies. Once imported, IntelliJ IDEA uses BSP to handle various project management tasks such as compiling, running, testing, and debugging your Scala code.

If you make changes to dependencies in the editor, a popup with a BSP icon will appear in the top-right corner. By clicking it, you can reload the BSP configuration.

[Video](https://resources.jetbrains.com/help/img/idea/2026.2/scalacli_bsp_reload.mp4)

Other changes to the project structure or dependencies, for example done via the command line, can be refreshed in the project in IntelliJ IDEA using the BSP panel.

If you write a ScalaCLI program based on another project with configuration in sbt, you can copy-paste an sbt dependency to a line starting with `//> using dep` and the text format will be changed automatically.

[Video](https://resources.jetbrains.com/help/img/idea/2026.2/sbt_to_scalacli.mp4)