SBT Aliases

February 27, 2025

If you want to create an alias for frequently used commands, group multiple commands together, or even rename a default command in your Scala project, you can create a Scala Build Tool (SBT) alias.

For example, I have an alias called "ci" and it runs multiple continuous integration commands in a project: clean;coverage;ca;check;analyze;test;coverageReport. I can easily type two characters in the SBT shell to execute a series of commands.

Aliases File

In the root of your Scala project, create a file called aliases.sbt. In that file you can add a command alias like so:

// aliases.sbt
addCommandAlias("<alias>", "<command>")

Replace <alias> and <command> with the values you want to use. For example, to make an alias that compiles all sources, both src and test, the alias can be anything you want, such as ca, and the command will be Test / compile:

// Compile all files; test and src
addCommandAlias("ca", "Test/compile")

To execute this alias from the command line, you can run sbt ca, or in the SBT shell you can execute ca

I learned of this handy feature from someone's tweet(?) on X a couple months ago, and then shortly after discovered a fantastic write-up on baeldung.com. I'm not sure why the addCommandAlias isn't in the SBT v1 or v2 documentation, but it should be. It's a great feature. The command is hidden in the depths of the SBT GitHub repository.

Samples

The following sample aliases are from a Scala 3 project I'm working on. I love the convenience of quickly calling a short alias to execute multiple commands.

/** Compile all files; test and src */
addCommandAlias("ca", "Test/compile")

/** Run tagged tests */
addCommandAlias("test-unit", "testOnly -- -ignore-tags integration")
addCommandAlias("test-integration", "testOnly -- -tags integration")

/**
  * Check all Scala files (src and test) for potential linting and code format issues. To fix
  * issues, see alias "fix".
  */
addCommandAlias("check", "lint;pretty")

/**
  * Fix all Scala files for linting and code format issues, should only be used for local
  * development purposes. Do NOT use this in CI.
  */
addCommandAlias("fix", "lint-fix;pretty-fix")

/**
  * Continuous Integration (CI) should clean, compile all, lint check, style format check, run tests
  * and generate test coverage reports. If any of these steps generate warnings, errors, or the code
  * coverage drops below the threshold specified in `build.sbt` then the build should fail.
  */
addCommandAlias("ci", "clean;coverage;ca;check;analyze;test;coverageReport")

/**
  * Check all Scala files (src and tests) for potential issues, this will not fix issues, see alias
  * "lint-fix".
  *
  * Lint rules are listed in the `scalafix.conf` file, found in the root directory of the project.
  */
addCommandAlias("lint", "scalafixAll --check")

/**
  * Fix all Scala files (src and tests) for linting issues. Do NOT use this alias when compiling in
  * the CI stage, prefer a lint check and fail if warnings/errors.
  *
  * Lint rules are listed in the `scalafix.conf` file, found in the root directory of the project.
  */
addCommandAlias("lint-fix", "scalafixAll")

/**
  * Check sbt and scala files (src and tests) for proper code style formatting. This will ONLY check
  * if the files have been formatted with Scalafmt, it will not apply formatting, see alias
  * "pretty-fix".
  *
  * Style rules are listed in the `scalafmt.conf` file, found in the root directory of the project.
  */
addCommandAlias("pretty", "scalafmtSbtCheck; scalafmtCheckAll")

/**
  * Fix all sbt and scala files (src and tests) for proper code style formatting. This will update
  * files to match the style formatting.
  *
  * Style rules are listed in the `scalafmt.conf` file, found in the root directory of the project.
  */
addCommandAlias("pretty-fix", "scalafmtSbt; scalafmtAll")

/** Static code analysis */
addCommandAlias("analyze", "scapegoat")

A big thanks to the SBT maintainers, such as Eugene Yokota, for all of the amazing work on this incredible tool. Thank you!

Dependencies

The following dependencies were used in this post.

Tags