Recorder CLI

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

--metadata                 A metadata.xml file (Android only)      
--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.
--build-url                Build URL to easily identify build that generated this run
--phabricator-diff-id      PHabricator Diff ID                     
--repo-url                 Repository URL (e.g.
--main-branch              Git Branch of the main branch being tracked
--branch                   Git Branch name for screenshot tracking 
--pull-request             Pull request URL                        
--channel                  Channel name for screenshot tracking    
--api-hostname             Screenshotbot API Endpoing              
--gitlab-merge-request-iid GitLab merge request IID                
--api-secret               Screenshotbot API Secret                
--create-github-issue      Create a Github issue if enabled on your account
--api-key                  Screenshotbot API Key                   
--verbose                  Verbose logs                            
--directory                Directory of images              

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.

Powered by BetterDocs