Commands

What is a “command”?

A “command” looks similar to a task: it’s a named operation that can be
executed from the sbt console.

However, a command’s implementation takes as its parameter the entire
state of the build (represented by State) and
computes a new State. This means that a command can
look at or modify other sbt settings, for example. Typically, you would
resort to a command when you need to do something that’s impossible in a
regular task.

Introduction

There are three main aspects to commands:

The syntax used by the user to invoke the command, including:

Tab completion for the syntax

The parser to turn input into an appropriate data structure

The action to perform using the parsed data structure. This action
transforms the build State.

Help provided to the user

In sbt, the syntax part, including tab completion, is specified with
parser combinators. If you are familiar with the parser combinators in
Scala’s standard library, these are very similar. The action part is a
function (State, T) => State, where T is the data structure produced
by the parser. See the
Parsing Input page for how to
use the parser combinators.

State provides access to the build state,
such as all registered Commands, the remaining commands to execute,
and all project-related information. See States and Actions for details on
State.

Finally, basic help information may be provided that is used by the
help command to display command help.

Defining a Command

A command combines a function State => Parser[T] with an action
(State, T) => State. The reason for State => Parser[T] and not
simply Parser[T] is that often the current State is used to build
the parser. For example, the currently loaded projects (provided by
State) determine valid completions for the project command. Examples
for the general and specific cases are shown in the following sections.

See Command.scala for the source
API details for constructing commands.