
=======
Running
=======

This page describes how to use `sbt` once you have set up your
project. It assumes you've :doc:`installed sbt <Setup>` and
created a :doc:`Hello, World <Hello>` or other project.

Interactive mode
----------------

Run sbt in your project directory with no arguments:

.. code-block:: console

    $ sbt

Running sbt with no command line arguments starts it in interactive
mode. Interactive mode has a command prompt (with tab completion and
history!).

For example, you could type :key:`compile` at the sbt prompt:

.. code-block:: console

    > compile

To :key:`compile` again, press up arrow and then enter.

To run your program, type :key:`run`.

To leave interactive mode, type `exit` or use Ctrl+D (Unix) or Ctrl+Z
(Windows).

Batch mode
----------

You can also run sbt in batch mode, specifying a space-separated list of
sbt commands as arguments. For sbt commands that take arguments, pass
the command and arguments as one argument to `sbt` by enclosing them
in quotes. For example,

.. code-block:: console

    $ sbt clean compile "testOnly TestA TestB"

In this example, :key:`testOnly` has arguments, `TestA` and `TestB`.
The commands will be run in sequence (:key:`clean`, :key:`compile`, then
:key:`testOnly`).

Continuous build and test
-------------------------

To speed up your edit-compile-test cycle, you can ask sbt to
automatically recompile or run tests whenever you save a source file.

Make a command run when one or more source files change by prefixing the
command with `~`. For example, in interactive mode try:

.. code-block:: console

    > ~ compile

Press enter to stop watching for changes.

You can use the `~` prefix with either interactive mode or batch mode.

See :doc:`/Detailed-Topics/Triggered-Execution` for more details.

Common commands
---------------

Here are some of the most common sbt commands. For a more complete list,
see :doc:`/Detailed-Topics/Command-Line-Reference`.

-  :key:`clean` Deletes all generated files (in the :key:`target` directory).
-  :key:`compile` Compiles the main sources (in `src/main/scala` and
   `src/main/java` directories).
-  :key:`test` Compiles and runs all tests.
-  :key:`console` Starts the Scala interpreter with a classpath including
   the compiled sources and all dependencies. To return to sbt, type
   `:quit`, Ctrl+D (Unix), or Ctrl+Z (Windows).
-  `run <argument>*` Runs the main class for the project in the same
   virtual machine as `sbt`.
-  :key:`package` Creates a jar file containing the files in
   `src/main/resources` and the classes compiled from
   `src/main/scala` and `src/main/java`.
-  `help <command>` Displays detailed help for the specified command.
   If no command is provided, displays brief descriptions of all
   commands.
-  `reload` Reloads the build definition (`build.sbt`,
   `project/*.scala`, `project/*.sbt` files). Needed if you change
   the build definition.

Tab completion
--------------

Interactive mode has tab completion, including at an empty prompt. A
special sbt convention is that pressing tab once may show only a subset
of most likely completions, while pressing it more times shows more
verbose choices.

History Commands
----------------

Interactive mode remembers history, even if you exit sbt and restart it.
The simplest way to access history is with the up arrow key. The
following commands are also supported:

-  `!` Show history command help.
-  `!!` Execute the previous command again.
-  `!:` Show all previous commands.
-  `!:n` Show the last n commands.
-  `!n` Execute the command with index `n`, as shown by the `!:`
   command.
-  `!-n` Execute the nth command before this one.
-  `!string` Execute the most recent command starting with 'string'
-  `!?string` Execute the most recent command containing 'string'

Next
----

Move on to :doc:`understanding build.sbt <Basic-Def>`.
