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.
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.
The source code and binaries for our CLI are available on our GitHub repository for macOS, Linux and Windows.
The latest available version of bugsnag-cli is v2.7.0.
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 --version-name=YOUR_APP_VERSION
You can find your API key in Project Settings from your BugSnag dashboard.
See the create-build command reference for details.
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.
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.
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.
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.
Upload dSYM files to allow BugSnag to show human-friendly function names, file paths, and line numbers in your iOS, macOS, and tvOS stacktraces.
To upload a dSYM, use the dsym command and specify your Xcode project or dSYM file directly:
$ bugsnag-cli upload dsym path/to/my-project.xcodeproj
See the dSYM command reference for full details.
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.
To get unminified stack traces for JavaScript code in your React Native app built for iOS, source maps must be generated and uploaded to BugSnag.
To upload source maps, use the react-native-ios command in the root of your React Native project:
$ bugsnag-cli upload react-native-ios
If your app follows a standard structure, all other parameters will be detected from your project files.
See the React Native iOS command reference for full details.
To get unminified stack traces for JavaScript code, source maps must be generated and uploaded to BugSnag.
To upload source maps, use the js command in the root of your project:
$ bugsnag-cli upload js --api-key=YOUR_API_KEY --base-url "https://example.com/js"
See the JavaScript command reference for full details.
When you build Android games with Unity using IL2CPP, a symbol ZIP file is generated containing the symbols used in your C# code as well as the Unity framework itself. These files should be uploaded, along with any ProGuard, DexGuard, or R8 mappings and NDK symbol files in order to show full stacktraces in your dashboard.
To upload these symbol files, use the unity-android command from your build directory:
$ bugsnag-cli upload unity-android \
--api-key my-api-key
See the Unity Android command reference for full details.