Getting started


Before getting started, sign your team up for Launchable: Sign up →

(Launchable is free for small teams and open source projects. Otherwise, we offer a free 60-day trial)

Implementing Launchable is a three step process:

  1. Recording builds

  2. Recording test results

  3. Subsetting test execution

The Launchable CLI enables this integration. To get started, install the CLI in your CI system, set your API key, then follow the instructions for your test runner or build tool.

Installing the CLI

The Launchable CLI is a Python3 package that you can install from PyPI:

Note that the CLI requires both Python 3.5+ and Java 8+.

pip3 install --user --upgrade launchable~=1.0
  • The --user flag installs the package in the local account without needing root access. This is handy when you are adding this to your build script for your CI server.

  • The --upgrade flag makes sure to always install the latest 1.x version.

Setting your API key

First, create an API key at (or use the one you received from us). This authentication token allows the CLI to talk to the Launchable service.

Then, you’ll need to make this API key available as the LAUNCHABLE_TOKEN environment variable in the parts of your CI process that interact with Launchable. How you do this depends on your CI system:

CI system


Azure DevOps Pipelines

Set secret variables

Bitbucket Pipelines

Variables and secrets


Using Environment Variables

GitHub Actions

How to configure a secret

GitLab CI

GitLab CI/CD environment variables


Setting variables on an environment


Injecting secrets into builds

(Create a global "secret text" to use in your job)

Travis CI

Environment Variables

Verifying connectivity

After setting your API key, you can run launchable verify in your script to test connectivity. If successful, you should receive an output such as:

$ launchable verify
Organization: <organization>
Workspace: <workspace>
Platform: macOS-11.2.3-x86_64-i386-64bit
Python version: 3.9.2
Java command: java
launchable version: 1.8.0
Your CLI configuration is successfully verified 🎉

If you get an error, see Troubleshooting.

It is always a good idea to run launchable verify in your build script, as this information is useful in case any problems arise. In that case, it is recommended to connect || true so that the exit status is always 0:

launchable verify || true

Next steps

Now that you've added the CLI to your pipeline, you can start optimizing your tests. The CLI natively integrates with the tools below. Click on the link to view instructions specific to your tool:

Not using any of these? Try the generic file based test runner option.