BugSnag is now Insight Hub – we're making some changes to how the product looks, but this won't impact the way you use BugSnag or any of your integrations.
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.
Installation
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.
NPM
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 CLI can also be executed using npx @bugsnag/cli.
Manual download
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 v3.2.1.
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 --version-name=YOUR_APP_VERSION
You can find your API key in your project’s settings (shortcut: gs) in the 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 your project’s settings (shortcut: gs) in the 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.
Breakpad symbols
To upload Breakpad symbol files, use the breakpad command and specify your BugSnag API key and the path directory to your .sym symbol files:
$ bugsnag-cli upload breakpad path/to/symbols/ --api=YOUR_API_KEY
See the Breakpad command reference for full details.
Dart
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.
dSYMs
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 locate and upload a dSYM from your project, use the dsym command from your Xcode project directory:
$ bugsnag-cli upload dsym
Alternatively, to provide more specific locations and options, use the xcode-archive command:
$ bugsnag-cli upload xcode-archive path/to/generated/MyApp.xcarchive
Or xcode-build command:
$ bugsnag-cli upload xcode-archive path/to/generated/project.dSYM
See the dSYM, Xcode build and Xcode archive command references for full details.
JavaScript source maps
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.
React Native symbols
Your React Native app can send stacktraces to BugSnag in both JavaScript format as well that of the native Android or Apple device. If the code in your app is obfuscated or minified then you will need to upload various files to BugSnag so that a full stacktrace with methods, file paths and line numbers can be shown.
To locate and upload these files, use the react-native command in the root of your React Native project:
$ bugsnag-cli upload react-native
See the React Native Android command reference for full details.
If your app follows a standard structure, all other parameters will be detected from your project files.
The different symbol file types can also be uploaded independently and with customized options using the following separate commands:
Unity Android symbol files
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=YOUR_API_KEY
See the Unity Android command reference for full details.