Command Line Reference

Complete reference for sbt command-line interface, commands, and options

sbt provides both an interactive shell and batch mode execution. This page documents available commands, command-line options, and usage patterns.

Running sbt

Interactive Mode

Start the sbt shell for interactive command execution:

$ sbt
sbt:my-project> compile
sbt:my-project> test
sbt:my-project> exit

Batch Mode

Execute commands and exit:

$ sbt compile
$ sbt clean test
$ sbt "testOnly com.example.MySpec"

Use quotes around commands with arguments to prevent shell interpretation.

Common Commands

Compilation Commands

compile · Command

Compiles main sources in the current project.

sbt compile
sbt Test/compile      # Compile test sources
sbt myProject/compile # Compile specific project

clean · Command

Deletes all generated files (target directory).

sbt clean
sbt clean compile     # Clean then compile

reload · Command

Reloads the build definition after changes to build.sbt or project/ files.

sbt:my-project> reload

sbt does not automatically reload after build definition changes. You must run reload manually.

Running Applications

run · Command

Runs the main class for the current project.

sbt run
sbt "run arg1 arg2"           # With arguments
sbt "run -Dprop=value arg1"   # With system properties

runMain · Command

Runs a specific main class.

sbt "runMain com.example.Main"
sbt "runMain com.example.Main arg1 arg2"

Testing Commands

test · Command

Runs all tests (or incrementally runs tests that failed or changed).

sbt test
sbt myProject/test    # Test specific project

testOnly · Command

Runs specific test classes or suites.

sbt "testOnly com.example.MySpec"
sbt "testOnly com.example.*Spec"
sbt "testOnly * -- -z \"test name\""

testQuick · Command

Runs tests that failed in previous runs or whose dependencies changed.

sbt testQuick

Interactive Commands

console · Command

Starts the Scala REPL with the project classpath.

sbt console

Type :quit or press Ctrl+D to exit the console.

consoleQuick · Command

Starts the Scala REPL with dependencies but without compiling project sources.

sbt consoleQuick

consoleProject · Command

Starts the Scala REPL with the sbt build definition on the classpath.

sbt consoleProject

Useful for debugging build definitions.

Package Commands

package · Command

Creates a JAR file containing compiled classes and resources.

sbt package
sbt Test/package      # Package test classes

Output: target/scala-<version>/<name>_<scalaVersion>-<version>.jar

packageSrc · Command

Creates a JAR file containing source files.

sbt packageSrc

packageDoc · Command

Creates a JAR file containing API documentation.

sbt packageDoc

Documentation Commands

doc · Command

Generates API documentation using Scaladoc.

sbt doc

Output: target/scala-<version>/api/

Dependency Commands

update · Command

Resolves and downloads dependencies.

sbt update

Usually not needed as it runs automatically when required.

dependencyTree · Command

Shows the dependency tree (requires sbt-dependency-graph plugin).

sbt dependencyTree

evicted · Command

Shows eviction warnings for conflicting dependencies.

sbt evicted

Command Prefixes

Configuration Scoping

Prefix commands with a configuration:

sbt Test/compile       # Compile test sources
sbt Test/run           # Run from Test configuration
sbt Compile/doc        # Generate docs for main sources

Project Scoping

For multi-project builds, scope commands to a specific project:

sbt core/compile       # Compile 'core' project
sbt api/test          # Test 'api' project
sbt cli/run           # Run 'cli' project

Combined Scoping

Combine project and configuration scopes:

sbt core/Test/compile
sbt api/Compile/packageBin

Command Composition

Sequential Execution

Run multiple commands in sequence using semicolons:

sbt clean; compile; test
sbt "clean; test"          # Quote when using in batch mode

Continuous Execution

Prefix a command with ~ for continuous/triggered execution:

sbt ~compile              # Recompile on source changes
sbt ~test                 # Rerun tests on changes
sbt "~testQuick"          # Continuous quick testing

Press Enter to stop continuous execution.

Multiple Projects

Use all to run a command on all projects:

sbt "all compile"         # Compile all projects
sbt "all test"            # Test all projects

sbt Launcher Options

Command-line options for the sbt launcher:

Memory Options

# Set maximum heap size
sbt -J-Xmx4G compile

# Set initial and maximum heap
sbt -J-Xms1G -J-Xmx4G test

# Set stack size
sbt -J-Xss4M compile

The -J prefix passes options directly to the JVM.

System Properties

# Set system property
sbt -Dproperty=value compile

# Multiple properties
sbt -Denv=prod -Dconfig=production run

sbt Options

-v · Flag

Enable verbose output.

sbt -v compile

-debug · Flag

Enable debug logging.

sbt -debug

--help · Flag

Display help information.

sbt --help

--version · Flag

Display sbt version.

sbt --version

-no-colors · Flag

Disable ANSI color codes in output.

sbt -no-colors test

--client · Flag

Force client mode (connect to existing server).

sbt --client compile

--batch · Flag

Force batch mode (no interactive shell).

sbt --batch clean test

Configuration Files

-Dsbt.global.base · Property

Override global sbt directory (default: ~/.sbt).

sbt -Dsbt.global.base=/custom/sbt compile

-Dsbt.ivy.home · Property

Override Ivy home directory (default: ~/.ivy2).

sbt -Dsbt.ivy.home=/custom/ivy compile

Shell Commands

Project Navigation

projects · Shell Command

List all projects in the build.

sbt:my-project> projects

project · Shell Command

Switch to a different project or display the current project.

sbt:root> project api
sbt:api> project
[info] api

Inspecting Settings

show · Shell Command

Display the value of a setting or task result.

sbt:my-project> show scalaVersion
[info] 3.3.1

sbt:my-project> show Test/definedTestNames

inspect · Shell Command

Display detailed information about a setting or task.

sbt:my-project> inspect scalaVersion
sbt:my-project> inspect compile

Session Management

session save · Shell Command

Save temporary settings to build.sbt.

sbt:my-project> set scalaVersion := "3.3.1"
sbt:my-project> session save

session clear · Shell Command

Clear all session settings.

sbt:my-project> session clear

Setting Values Temporarily

set · Shell Command

Set a value for the current session.

sbt:my-project> set scalaVersion := "2.13.12"
sbt:my-project> set Test/fork := true

Changes are lost when exiting sbt unless saved with session save.

Help Commands

help · Shell Command

Display help for commands.

sbt:my-project> help
sbt:my-project> help compile
sbt:my-project> help run

tasks · Shell Command

List available tasks.

sbt:my-project> tasks
sbt:my-project> tasks -v    # Verbose listing

settings · Shell Command

List available settings.

sbt:my-project> settings
sbt:my-project> settings -v  # Verbose listing

Environment Variables

SBT_OPTS · Environment Variable

JVM options for sbt.

export SBT_OPTS="-Xmx4G -XX:+UseG1GC"
sbt compile

JAVA_OPTS · Environment Variable

Additional JVM options (merged with SBT_OPTS).

export JAVA_OPTS="-Duser.timezone=UTC"

JAVA_HOME · Environment Variable

Java installation directory.

export JAVA_HOME=/usr/lib/jvm/java-17
sbt compile

Common Workflows

Development Workflow

# Start sbt shell
$ sbt

# Continuous compilation
sbt:my-project> ~compile

# In another terminal: edit code
# sbt automatically recompiles on save

# Switch to continuous testing
sbt:my-project> ~testQuick

Clean Build

sbt clean compile test package

Multi-Project Workflow

$ sbt
sbt:root> projects
[info]   * root
[info]     core
[info]     api
[info]     cli

sbt:root> project core
sbt:core> compile

sbt:core> project
[info] core

sbt:core> project root
sbt:root> all test

Release Workflow

sbt clean test package
sbt publish

Best Practices

1. Use Interactive Shell for Development

# Good: Fast iteration with shell
$ sbt
sbt:my-project> ~testQuick

# Avoid: Slow batch mode for repeated commands
$ sbt test
$ sbt test
$ sbt test

2. Use Batch Mode for CI/CD

# Good: Clear, explicit CI command
sbt clean coverage test coverageReport

# Avoid: Interactive mode in CI
sbt  # Then typing commands

3. Quote Commands with Arguments

# Good: Proper quoting
sbt "testOnly com.example.*Spec"

# Bad: Shell interprets *
sbt testOnly com.example.*Spec

4. Use .sbtopts for Project-Specific Options

Create a .sbtopts file in the project root:

# .sbtopts
-J-Xmx4G
-J-XX:+UseG1GC
-Dsbt.color=true

5. Use Continuous Execution

# Efficient development
sbt:my-project> ~testQuick

# Avoid: Manual repeated execution
sbt:my-project> test
sbt:my-project> test
sbt:my-project> test

Exit Codes

sbt returns exit codes for scripting:

Exit Code	Meaning
0	Success
1	Error (compilation failure, test failure, etc.)
130	Interrupted (Ctrl+C)

sbt test && echo "Tests passed" || echo "Tests failed"

See Also

• Settings and Tasks - Understanding what commands execute
• Configurations - Scoping commands to configurations
• Directory Structure - Understanding project layout