TestFairy Command Line Upload Script – Setup and Usage

TestFairy provides a command-line interface (CLI) and REST API that allows Android developers to automate build uploads to the TestFairy platform. This is essential in continuous integration (CI/CD) workflows and for automating distribution to testers.

This guide explains how to install and use the CLI upload script, configure required options, and integrate it into your automation pipeline.

What Is TestFairy CLI Upload Script?

A command line upload script for TestFairy is a small automation tool that takes your built Android APK or AAB file and uploads it directly to your TestFairy project using your TestFairy API key.

The script interacts with the TestFairy Upload API using HTTP form uploads (e.g., curl or a packaged CLI tool).

Why Use Command Line Upload?

Using a script to upload your app build gives you:

• Scriptable automation for CI/CD pipelines
• Consistent upload settings
• Ability to include tester groups and release notes
• Option to integrate directly with tools like Jenkins, GitLab, GitHub Actions, Bitrise

Uploading builds manually is slow and error-prone in automated workflows.

Pre-Requisites

Before you can use the script:

1. TestFairy Account – Sign in and retrieve your API Key from TestFairy dashboard settings.
2. APK or AAB Build Artifact – Your compiled Android package ready for upload.
3. Command Line Tool (optional) – Use curl or an npm uploader like testfairy-uploader for more features.

Basic Upload Using curl

The most common and direct method is to use the TestFairy Upload API with curl. The Upload API endpoint accepts form-based uploads.

Sample curl Upload

curl https://app.testfairy.com/api/upload \
  -F api_key="YOUR_TESTFAIRY_API_KEY" \
  -F file=@app-release.apk

This command will upload your APK to TestFairy and return JSON indicating success, build ID, and download URLs.

Using Optional Parameters

The API supports additional parameters to enrich your upload:

Example with fields:

curl https://app.testfairy.com/api/upload \
  -F api_key="YOUR_KEY" \
  -F file=@app-release.apk \
  -F notify="on" \
  -F release_notes="Automated CI build"

This script will upload and notify testers.

Using npm “testfairy-uploader” Script

There are Node-based uploader tools like testfairy-uploader that wrap upload logic in a CLI. After installing:

npm install -g testfairy-uploader

You can upload a build with:

testfairy-uploader \
  --api-key YOUR_API_KEY \
  --keystore=KEYSTORE_PATH \
  --storepass=KEYSTORE_PASSWORD \
  --alias=KEYSTORE_ALIAS \
  /path/to/app-release.apk

This simplifies uploads and lets you configure parameters in a script.

Integrating into CI/CD (Jenkins, GitLab)

In CI systems like Jenkins or GitLab, include a shell step to invoke the upload script or direct curl command after your build step. For example:

Jenkins Shell Step

./testfairy-upload.sh ./app/build/outputs/apk/release/app-release.apk

Ensure that your script includes the API key and upload options. This automates distribution for every successful build.

Automating with Environment Variables

To avoid exposing secrets:

1. Store your TestFairy API Key in CI environment settings.
2. Reference them when running upload.

Example GitLab:

variables:
  TESTFAIRY_API_KEY: $TESTFAIRY_API_KEY

script:
  - curl https://app.testfairy.com/api/upload -F api_key=$TESTFAIRY_API_KEY -F file=@app-release.apk

This script fetches your release artifact and uploads it securely.

Debugging Upload Failures

Common upload issues include:

• Invalid or missing API key
• File path incorrect
• Network or proxy restrictions

Ensure the file path starts with @ in curl commands and your API key is valid. Also verify TestFairy dashboard settings.

Best Practices

• Use secure secrets management in CI tools.
• Automate uploads every time a staging or release build completes.
• Add meaningful release notes to aid testers.
• Group testers to control notifications.

Conclusion

Using a TestFairy command line upload script lets Android teams automate build distribution seamlessly. Whether via curl, an npm uploader, or CI integration, this approach increases efficiency and reliability.