Conscript is a distribution mechanism for Scala apps using GitHub and Maven repositories as the infrastructure. You can use it to install and update apps similar to APT or Home Brew.

It does less than you think, because the sbt launcher does more than you think. More on that later.

Installing conscript 

Set up environment variables 

Depending on your OS the format might be different, but set up the following three environment variables.

export CONSCRIPT_HOME="$HOME/.conscript"
export CONSCRIPT_OPTS="-XX:MaxPermSize=512M -Dfile.encoding=UTF-8"
  • CONSCRIPT_HOME is where Conscript will download various files.
  • CONSCRIPT_OPTS is JVM arguments passed on to the apps that you installed using Conscript.
  • By default Conscript will create the launching script for the apps in $CONSCRIPT_HOME/bin. Optionally you can change this location using $CONSCRIPT_BIN for example to ~/bin/
  • PATH is your OS’s path variable. Add $CONSCRIPT_HOME/bin or $CONSCRIPT_BIN to the path.

There are three methods of installation available

Cross platform 

Download the conscript runnable jar. On most OSes you can run it by double-clicking, but if that doesn’t work you can also run it from the command line.

$ java -jar conscript_2.11-0.5.8-proguard.jar

A “splash screen” will appear during installation. Don’t close it until you see a message that cs was installed, or that something went wrong.

Linux, Mac 

If you prefer, you can install conscript by piping this shell script.

wget -O - | sh


If you prefer, you can download the PowerShell script and run it.

Using conscript 

The main thing you do with conscript is install and update commands based on launchconfig. launchconfig files are stored in GitHub projects, which you pass into the cs command. For example, this installs the giter8 templating system:

$ cs foundweekends/giter8

launchconfigs specify a version of the app to use, but you can override that by specifying an explicit version with another slash:

$ cs foundweekends/giter8/0.2.1

Project owners may also decide to push pre-release or other alternate launchconfig to different branches on GitHub. Use can tell conscript read launchconfigs from another branch with the --branch or -b option.

$ cs foundweekends/giter8 --branch staging

Cleaning boot directory 

If at some point your conscript boot directory contains stale/suspect artifacts such as snapshot releases, you can clean it:

$ cs --clean-boot

When you next run any conscripted app (such as cs) it will fetch its cleaned dependencies back into the shared boot directory; generally it only has to look as far as the local ivy cache to find them.

How does conscript work? 

Conscript does less than you think, because the sbt launcher does more than you think. What?

What conscript does:

  • Queries a GitHub project for launchconfigs (launcher configurations)
  • Copies launchconfigs to your local filesystem, with a personalized boot path
  • Creates scripts to execute the launch configurations

What sbt launcher does:

  • Reads a given launchconfig
  • Fetches needed dependencies on the first run
  • Uses the same Ivy cache as sbt itself

So conscript just assumes a convention and helps you adhere to it. Suppose you’ve configured $CONSCRIPT_HOME to $HOME/.conscript.

Then $CONSCRIPT_HOME/boot is used as a boot directory for all. App launchconfigs are stored according to the GitHub project name and the script name, such as:


And finally, shell scripts are created in $CONSCRIPT_BIN (default: $CONSCRIPT_HOME/bin) that reference launchconfigs, for example, ~/.conscript/bin/cs. This is how the shell script looks like on Mac:

java -jar /Users/foo/.conscript/sbt-launch.jar \
  @/Users/foo/.conscript/foundweekends/conscript/cs/launchconfig "$@"

Once the shell script is created, now it’s up to the sbt launcher to carry out the actual work of fetching artifacts and running the app.

Private repositories 

Conscript supports private github repos using github’s oauth flow for non-web apps.

To authenticate and store a permanent token, use the --auth parameter:

$ cs --auth yourname:yourpass

This stores an access token in ~/.conscript/config which is used for all future cs invocations. You can revoke tokens at any time in your GitHub account settings.

The sbt launcher can access private Maven/Ivy repos just as sbt itself can. Specify a credentials properties file, such as ~/.ivy2/.credentials, in the sbt.boot.credentials JVM property or SBT_CREDENTIALS environment variable. The launcher will use these credentials when accessing protected resources in the specified realm.

Making a conscripted app 

We hope you’ll make your own apps that use conscript.


The ConscriptPlugin makes these easier to build and test. Add this to the following project/conscript.sbt:

addSbtPlugin("org.foundweekends.conscript" % "sbt-conscript" % "0.5.8")

Next enable ConscriptPlugin on the app subproject in build.sbt:

lazy val root = (project in file(".")).
    // other settings here

The plugin brings in a “provided” dependency to sbt launcher-interface.

Entry point 

Make the entry point to your app by implementing xsbti.AppMain.

package example

class HelloApp extends xsbti.AppMain {
  def run(configuration: xsbti.AppConfiguration): xsbti.MainResult = {
    // get the version of Scala used to launch the application
    val scalaVersion = configuration.provider.scalaProvider.version

    // Print a message and the arguments to the application
    println("Hello world!  Running Scala " + scalaVersion)

    new Exit(0)
  class Exit(val code: Int) extends xsbti.Exit

After one or two command line options, you might want to take a look at scopt to do commandline parsing.


Next, add your sbt launchconfig file to src/main/conscript/XYZ/launchconfig (substitue XYZ with your script name such as g8 and cs):

  version: 0.1.0
  org: com.example
  name: hello
  class: example.HelloApp
  version: 2.11.12

To learn more about the launchconfig, see sbt Launcher section of the sbt Reference Manual.


You can test the app by calling csRun XYZ command.

Conscripted apps 

Because conscipt uses a known path /src/main/conscript/ on GitHub, we can search the GitHub repos to discover conscripted apps.

Let us know if you’ve written a conscripted app.