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.

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


 --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
 --branch                [OBSOLETE]                              
 --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                     
 --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
 --ios-diff-dir          When using ios-snapshot-test-case, this can link to the
                          IMAGE_DIFF_DIR. In most cases this isn't required, but it can be
                          useful for backward compatibility if you don't want to update the
                          tests to always work in recorde mode.
 --main-branch           Git Branch of the main branch being tracked. We try first
                          `main` and then `master`, by checking for origin/<branch-name>
 --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.
 --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                     
 --pull-request          Pull request URL. Automatically detected on CircleCI,
                          Bitrise, Netlify.
 --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.
 --verbose               Verbose logs                            
 --version               Show the version of this SDK and exit   

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.