BugSnag CLI

The BugSnag CLI can be used to simplify the process of creating releases on the BugSnag dashboard and uploading files to improve the stacktraces in your errors.

This guide provides installation and usage information for the platforms that are currently supported by the CLI.


Install script

To install or upgrade to the latest binary for your architecture, run the following cURL or Wget commands:

curl -o- https://raw.githubusercontent.com/bugsnag/bugsnag-cli/main/install.sh | bash
wget -qO- https://raw.githubusercontent.com/bugsnag/bugsnag-cli/main/install.sh | bash

The script downloads the appropriate binary and attempts to install it to $HOME/.local/bugsnag.


If your project uses npm or yarn, the CLI can be installed by adding the @bugsnag/cli package, and can then be executed from your project scripts at /node_modules/.bin/bugsnag-cli.

Manual download

The source code and binaries for our CLI are available on our GitHub repository for macOS, Linux and Windows.

Creating builds

Allows you to create a build within BugSnag to enrich releases shown in the BugSnag dashboard.

For example:

$ bugsnag-cli create-build --api-key=YOUR_API_KEY --app-version=YOUR_APP_VERSION

You can find your API key in Project Settings from your BugSnag dashboard.

See the create-build command reference for details.

Symbol & mapping file uploads

For many platforms, different types of source code and mapping files are required in order to show a meaningful stacktrace. For each supported platform, the CLI uploads the required files from your build directory to the appropriate BugSnag API.

Below are each of the platforms along with available options. Where possible default values for these options are parsed from your project files, but can be overridden by passing a value on the command line.

You can find your API key in Project Settings from your BugSnag dashboard.

Android App Bundles (AABs)

If you distribute your app as an Android App Bundle (AAB), they contain all required files and so can be uploaded in a single command.

The android-aab extracts the required files and uploads them along with version information also found in within the bundle:

$ bugsnag-cli upload android-aab app/build/outputs/bundle/release/app-release.aab

See the Android AAB command reference for full details.

Android NDK mapping files

For apps that use the NDK, native stacktraces from C or C++ code consist of a list of addresses and numeric offsets. BugSnag requires a mapping file to be uploaded to match a given address with a file name and method.

The android-ndk command extracts NDK symbols from .so files and uploads them along with version information from your project directory:

$ bugsnag-cli upload android-ndk

See the Android NDK command reference for full details.

Android Proguard mapping files

If you are using ProGuard, DexGuard, or R8 to minify and optimize your app this will cause method and class names to become obfuscated in your stacktraces. Upload a mapping.txt file from a Proguard obfuscation build to deobfuscate symbols in your reported stacktraces.

The android-proguard command uploads the mapping file along with version information from your project directory:

$ bugsnag-cli upload android-proguard

See the Android Proguard command reference for full details.


If you are stripping debug symbols from your Dart code when building your Flutter apps, you will need to upload symbol files in order to see full stacktraces in BugSnag.

To upload these symbols, use the dart command and specify your BugSnag API key and the directory of the generated symbol files:

$ bugsnag-cli upload dart --api-key=YOUR_API_KEY app-debug-info/

See the Dart command reference for full details.

React Native Android source maps

To get unminified stack traces for JavaScript code in your React Native app built for Android, source maps must be generated and uploaded to BugSnag.

To upload source maps, use the react-native-android command in the root of your React Native project:

$ bugsnag-cli upload react-native-android

If your app follows a standard structure, all other parameters will be detected from your project files.

See the React Native Android command reference for full details.