Command Line Interface

The recorder command line tool is the primary interface for you to upload screenshots to Screenshotbot. It’s a simple script that you can run at the end of the tests. The source code for the script is available on GitHub.


You can build this script from the Open Source repository, or you can install the latest version at any time using the following command:

    curl | sh

This will install the script at ~/screenshotbot/recorder. You may call this from your CI jobs. You’re welcome to use this script even if you’re using the open source version of Screenshotbot, however, we suggest you let us know so that we can ensure that our CDN can be optimized for your needs.

This installation process works for 64-bit Linux, and 64-bit Mac OS (both Intel and ARM). For any other platform (including Windows), please reach out to us, or build the binary from scratch from our Open Source repository.

Invoking from CI

When invoking from your CI, our command line tool will read environment variables to get most of the information we need automatically. Typically you need only the following two lines:

      git fetch origin main
      ~/screenshotbot/recorder --directory path/to/screenshots/ --channel-name channel

We recommend the git fetch before calling our tool. On some CI frameworks, the main or master branch is not fetched when running a job on Pull Requests, and we use the main branch information to figure out which commit we should generate reports against. Please make sure you're passing the right branch that corresponds to the main branch.

If your main branch is not main or master you must pass it to the recorder tool using --main-branch branch-name argument.

Overview of CLI options

This is the full list of CLI options (as seen with --help), we’ll go over the important details in the next section.

Screenshotbot Recorder script

Usage: recorder [options]

Use this script from your CI pipelines or locally to
upload screenshots and generate reports

We are currently migrating the commands from a single top-level
command to multiple subcommands. Use `recorder help` to get documentation
for subcommands.


 --api-hostname          Screenshotbot API Endpoint              
 --api-key               Screenshotbot API Key. Defaults to $SCREENSHOTBOT_API_KEY.
 --api-secret            Screenshotbot API Secret. Defaults to $SCREENSHOTBOT_API_SECRET
 --author                Author for this run. Either in the form of "Full Name <>" or just "". The email is used to enforce review rules.
 --batch                 Batch multiple channels into one single build status named by this
 --browser-configs       A YAML file that specifies the configuration of the
                          browsers. Please see documentation for details.
 --build-url             Build URL to easily identify build that generated this run
 --channel               Channel name for screenshot tracking. Defaults to `unnamed-channel`.
 --commit-limit          Limit the number of commits for which we upload commit hashes. This is
                          useful for large repositories (about > 10000 commits). For large
                          repositories, sending all the commit hashes will time out. The
                          uploaded graph is merged with the graph that the server already knows
                          You should set this high enough so that Screenshotbot always has the
                          entire commit graph from the previous promoted run to the new run. A
                          value of about 1000 should be safe and relatively fast for most
 --compare-threshold     Fraction of pixels that can be different for Screenshotbot to consider
                          the screenshots to be the same. (between 0.0 and 1.0)
                          We don't recommend using this unless absolutely required. Flaky
                          screenshots are harder to maintain long term. Using this argument can
                          also slow down the processig of your reports significantly.
                          If not specified, or if specified by 0.0, we'll consider screenshots
                          equal only if they are identical by file content. (e.g. any changes in
                          encoding, or EXIF data will cause a screenshot change.)
                          Keep in mind that this value will typically be very low. e.g., a
                          1000x1000 image, using 0.001 threshold would still allow for 1000
                          pixel changes which might be too high for most practical uses. You
                          probably want to choose this so that no more than 10-20 pixels are
                          allowed to be different at a time.
 --create-github-issue   Create a Github issue if enabled on your account
 --desktop               Whether running in desktop mode. In desktop mode the --hostname
                          defaults to http://localhost:4095, and authentication is disabled.
 --directory             Directory of images                     
 --finalize              Notify Screenshotbot that all builds on all channels on this
                          commit are complete. This is not required to be called, but if
                          used provides a better developer experience when later builds
                          are waiting on this commit.
 --firebase-output       When running Android tests in Firebase Test Lab, pass the output of
                          the `gcloud firebase test android run` as a file to this option. We'll
                          automatically fetch the required files from Google Cloud, and clean
                          up  the files from Google Cloud when we're done. We use the `gcloud`
                          command line tool so you must have already called
                          activate-service-account before this step.
                         GitLab merge request IID
 --main-branch           Git Branch of the main branch being tracked. We try first
                          `main` and then `master`, by checking for origin/<branch-name>
                         The commit of the main branch at time of running. In most case, you
                          DO NOT need to provide this, and we'll detect this from the Git repository
                          directly. Please contact if you plan on using this.
 --mark-failed           Mark this run as failed. This might happen if the build step that
                          generates the screenshots failed.
                          You don't need to call this, but if you do we can use the information
                          to show more appropriate information on Pull Requests. For instance,
                          if you have a Pull Request based off of a failing commit, we can find
                          the last green commit to make our screenshot report.
 --mark-unchanged-from   Notify Screenshotbot that the run for this commit will be identical
                          to the run from the commit provided
                         Override the merge base commit. In most cases, you do not
                          need to provide this, and it will be computed automatically (as
                          `git merge-base main this-branch`).The merge base is only use on PR
                          commits, to figure out which commit to compare screenshots against.
                          This might be useful to override if you don't have access to the
                          repository when calling this CLI, or implementing custom behavior with
                          stacked Pull Requests.
 --metadata              A metadata.xml file (Android only)      
 --override-commit-hash  Override the commit hash detected by git. In most cases you
                          don't need this, and this is only relevant for Pull Requests, and
                          only if you rebase your changes as part of your CI run. This hash
                          must be the full hash, partial hashes or tag names are not
                          Automatically detected on: CircleCI, Bitrise
 --phabricator-diff-id   Phabricator Diff ID                     
 --production            Whether this is a run on your CI. For local runs, we
                          suggest using `--production=false`. This avoids polluting your runs
                          in production.
 --pull-request          Pull request URL. Automatically detected on CircleCI,
                          Bitrise, Netlify.
 --recursive             Whether to scan the directory recursively
 --repo-url              Repository URL (e.g.
 --self-test             Run self-diagnostic tools to ensure that this CLI can work on your
 --static-website        Use to generate screenshots of a static website
                         When parsing the website directory at --static-website, the
                          asset root is used to determine where to fetch JS, CSS and image
                          from. If not specified, we assume the assets are all stored in the
                          same directory.
 --tags                  A comma separated list of tags to associate with these runs. Tags are arbitrary and will be shown next to the run names, and let's you filter runs by tags.
 --verbose               Verbose logs                            
 --version               Show the version of this SDK and exit   
 --work-branch           Your current branch, preferably as provided by your CI environment
                          as opposed to reading from git. Some CI environments may not update the
                          local branch name, and instead provides the branch name as an environment
                          variable. We can automatically figure this out on CircleCI, Bitrise,
                          Netlify, Azure DevOps, BuildKits, and Bitbucket Pipelines.

Copyright 2020-2022 Modern Interpreters Inc.
Please reach out to for any questions

Example usage for a generic iOS/web project

For a generic iOS or web project, we’ll expect you to store all the screenshots at the end of the CI run into a directory. This directory should not be committed into the git repository. At the end of the CI run, you can invoke the CLI script:

    ~/screenshotbot/recorder \
         --directory path/to/screenshots/ \
         --channel some-project-name \
         --main-branch master \
         --api-key ${SCREENSHOTBOT_API_KEY} \
         --api-secret ${SCREENSHOTBOT_API_SECRET} \

The repo URL is used for certain source control integrations. For example, with GitHub it is used for the Checks API (but make sure you install the Screenshotbot app to your project, and give it permissions to your repo. The Screenshotbot app only has access to the checks API and nothing else).

The channel is an arbitrary name that you can think of as a project id. The main-branch will always point to your master or main branch. It defaults to master. This branch is used to track the history of the screenshots, and for pull requests it is used to determine which branch to compare against.

Example usage for Android project

Everything above applies for the Android project. Except we have special integrations for screenshot-tests-for-android and Shot, especially when using Firebase Test Lab.

You can see an example of this here.

Ready to get started?

Sign up or contact us.