Keys API

Core setting and task keys in sbt for project configuration and build execution

Keys API

The Keys object (defined in sbt.Keys) provides all the core settings and task keys used throughout sbt. These keys are the fundamental building blocks for configuring your build.

Project Identity Keys

name

val name: SettingKey[String]

Project name.

name · SettingKey[String] · required

The name of the project. This is used for dependency management, artifact naming, and display purposes.

Example:

name := "my-project"

Location: Keys.scala:402

organization

val organization: SettingKey[String]

Organization/group ID for the project.

organization · SettingKey[String] · required

The organization or group identifier, typically in reverse domain notation (e.g., “com.example”).

Example:

organization := "com.example"

Location: Keys.scala:408

version

val version: SettingKey[String]

The version/revision of the current module.

version · SettingKey[String] · required

Semantic version string for the project (e.g., “1.0.0”, “0.1.0-SNAPSHOT”).

Example:

version := "1.0.0"

Location: Keys.scala:599

Scala Configuration Keys

scalaVersion

val scalaVersion: SettingKey[String]

The version of Scala used for building.

scalaVersion · SettingKey[String] · required

Scala version for compilation (e.g., “2.13.12”, “3.3.1”).

Example:

scalaVersion := "3.3.1"

Location: Keys.scala:228

scalaBinaryVersion

val scalaBinaryVersion: SettingKey[String]

The Scala version substring describing binary compatibility.

scalaBinaryVersion · SettingKey[String]

Binary version used for cross-building (e.g., “2.13” for Scala 2.13.x, “3” for Scala 3.x).

Location: Keys.scala:230

crossScalaVersions

val crossScalaVersions: SettingKey[Seq[String]]

The versions of Scala used when cross-building.

crossScalaVersions · SettingKey[Seq[String]]

List of Scala versions to build against when running +compile, +publish, etc.

Example:

crossScalaVersions := Seq("2.13.12", "3.3.1")

Location: Keys.scala:232

scalaOrganization

val scalaOrganization: SettingKey[String]

Organization/group ID of the Scala used in the project.

scalaOrganization · SettingKey[String]

Default value is "org.scala-lang". Advanced setting for Scala language clones.

Location: Keys.scala:227

Dependency Management Keys

libraryDependencies

val libraryDependencies: SettingKey[Seq[ModuleID]]

Declares managed dependencies.

libraryDependencies · SettingKey[Seq[ModuleID]] · required

List of library dependencies for the project. Use %, %%, or %%% operators to declare dependencies.

Example:

libraryDependencies ++= Seq(
  "org.typelevel" %% "cats-core" % "2.10.0",
  "org.scalatest" %% "scalatest" % "3.2.17" % Test
)

Location: Keys.scala:627

resolvers

val resolvers: SettingKey[Seq[Resolver]]

The user-defined additional resolvers for automatically managed dependencies.

resolvers · SettingKey[Seq[Resolver]]

Custom Maven or Ivy repositories to search for dependencies.

Example:

resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/snapshots"

Location: Keys.scala:608

Compilation Keys

compile

val compile: TaskKey[CompileAnalysis]

Compiles sources.

compile · TaskKey[CompileAnalysis] · required

Main compilation task that processes Scala and Java sources.

Example:

Compile / compile
Test / compile

Location: Keys.scala:262

scalacOptions

val scalacOptions: TaskKey[Seq[String]]

Options for the Scala compiler.

scalacOptions · TaskKey[Seq[String]]

Command-line flags passed to the Scala compiler (e.g., -deprecation, -feature).

Example:

scalacOptions ++= Seq(
  "-deprecation",
  "-feature",
  "-Xfatal-warnings"
)

Location: Keys.scala:209

javacOptions

val javacOptions: TaskKey[Seq[String]]

Options for the Java compiler.

javacOptions · TaskKey[Seq[String]]

Command-line flags passed to the Java compiler.

Example:

javacOptions ++= Seq("-source", "11", "-target", "11")

Location: Keys.scala:210

Directory and Path Keys

baseDirectory

val baseDirectory: SettingKey[File]

The base directory. Depending on the scope, this is the base directory for the build, project, configuration, or task.

baseDirectory · SettingKey[File] · required

Root directory of the project, typically where build.sbt is located.

Location: Keys.scala:147

sourceDirectory

val sourceDirectory: SettingKey[File]

Default directory containing sources.

sourceDirectory · SettingKey[File]

Defaults to src in the base directory.

Location: Keys.scala:154

scalaSource

val scalaSource: SettingKey[File]

Default Scala source directory.

scalaSource · SettingKey[File]

Defaults to src/main/scala for Compile configuration, src/test/scala for Test.

Location: Keys.scala:156

target

val target: SettingKey[File]

Main directory for files generated by the build.

target · SettingKey[File]

Output directory for compiled classes, packaged JARs, and other generated artifacts.

Location: Keys.scala:150

classDirectory

val classDirectory: SettingKey[File]

Directory for compiled classes and copied resources.

classDirectory · SettingKey[File]

Defaults to target/scala-<version>/classes for main sources.

Location: Keys.scala:189

Package and Publish Keys

packageBin

val packageBin: TaskKey[HashedVirtualFileRef]

Produces a main artifact, such as a binary JAR.

packageBin · TaskKey[HashedVirtualFileRef]

Creates the primary packaged artifact for the project.

Example:

Compile / packageBin

Location: Keys.scala:314

publish

val publish: TaskKey[Unit]

Publishes artifacts to a repository.

publish · TaskKey[Unit]

Uploads artifacts to the resolver specified by publishTo.

Location: Keys.scala:588

publishLocal

val publishLocal: TaskKey[Unit]

Publishes artifacts to the local Ivy repository.

publishLocal · TaskKey[Unit]

Installs artifacts in the local Ivy cache (~/.ivy2/local).

Location: Keys.scala:589

publishTo

val publishTo: TaskKey[Option[Resolver]]

The resolver to publish to.

publishTo · TaskKey[Option[Resolver]]

Specifies the repository where artifacts will be published.

Example:

publishTo := Some("releases" at "https://repo.example.com/releases")

Location: Keys.scala:639

Test Keys

test

val test: InputKey[TestResult]

Executes the tests that either failed before, were not run, or whose transitive dependencies changed.

test · InputKey[TestResult]

Runs tests incrementally based on changes.

Location: Keys.scala:378

testOnly

val testOnly: InputKey[TestResult]

Executes the tests provided as arguments or all tests if no arguments are provided.

testOnly · InputKey[TestResult]

Selective test execution by test class name or pattern.

Example:

testOnly com.example.MySpec

Location: Keys.scala:380

testFrameworks

val testFrameworks: SettingKey[Seq[TestFramework]]

Registered, although not necessarily present, test frameworks.

testFrameworks · SettingKey[Seq[TestFramework]]

Test framework implementations (ScalaTest, specs2, JUnit, etc.).

Location: Keys.scala:386

Run Keys

run

val run: InputKey[Unit | ClientJobParams]

Runs a main class, passing along arguments provided on the command line.

run · InputKey[Unit | ClientJobParams]

Executes the application’s main method.

Example:

run
run arg1 arg2

Location: Keys.scala:337

mainClass

val mainClass: TaskKey[Option[String]]

Defines the main class for packaging or running.

mainClass · TaskKey[Option[String]]

Fully qualified name of the main class to execute.

Example:

Compile / mainClass := Some("com.example.Main")

Location: Keys.scala:336

fork

val fork: SettingKey[Boolean]

If true, forks a new JVM when running. If false, runs in the same JVM as the build.

fork · SettingKey[Boolean]

Controls process isolation for running applications and tests.

Location: Keys.scala:343

Logging Keys

logLevel

val logLevel: SettingKey[Level.Value]

Controls the logging level.

logLevel · SettingKey[Level.Value]

Values: Level.Error, Level.Warn, Level.Info, Level.Debug

Location: Keys.scala:56

Clean Keys

clean

val clean: TaskKey[Unit]

Deletes files produced by the build, such as generated sources, compiled classes, and task caches.

clean · TaskKey[Unit]

Removes all build artifacts and intermediate files.

Location: Keys.scala:258

Additional Keys

description

val description: SettingKey[String]

Project description.

description · SettingKey[String]

Human-readable description of the project.

Location: Keys.scala:404

licenses

val licenses: SettingKey[Seq[License]]

Project licenses as (name, url) pairs.

licenses · SettingKey[Seq[License]]

Open source or proprietary licenses for the project.

Example:

licenses := Seq("Apache-2.0" -> url("https://www.apache.org/licenses/LICENSE-2.0.txt"))

Location: Keys.scala:407

homepage

val homepage: SettingKey[Option[URI]]

Project homepage.

homepage · SettingKey[Option[URI]]

URL to the project website or repository.

Location: Keys.scala:405

Key Operators

Keys support various operators for setting and modifying values:

• := - Sets a value
• += - Appends a single value to a sequence
• ++= - Appends multiple values to a sequence
• --= - Removes values from a sequence

// Setting a value
name := "my-project"

// Appending to a sequence
libraryDependencies += "org.typelevel" %% "cats-core" % "2.10.0"

// Appending multiple values
scalacOptions ++= Seq("-deprecation", "-feature")