Introducing Raygun CLI: Level-up your error tracking workflow

Raygun CLI is a powerful command-line interface tool designed to enhance the developer experience when working with Raygun’s error tracking and performance monitoring platform.

With this tool, we bring Raygun’s features directly to your terminal, making it easier to integrate some important elements of Raygun Crash Reporting and error tracking into your development and CI/CD workflow.

We are excited to announce the release of version 1.0.0 of Raygun CLI

What’s in this article:

• What is Raygun CLI
  • Deployment management
    • Why is this important for a well-functioning error monitoring setup?
  • Source maps management
  • Debug and obfuscation symbols upload
    • Flutter
    • Android
• Technical implementation and why we used Dart
• Getting started
• Configuration
• Future development
• Conclusion

What is Raygun CLI?

Raygun CLI is an MIT-licensed, open-source command-line tool written in Dart that provides developers direct access to Raygun’s API functionality from the command line.

We created Raygun CLI to help developers automate common tasks when working with Raygun:

• Manage deployment notifications
• Handle the upload of source maps, symbols, and ProGuard mappings

Let’s have a look at the key features of Raygun-CLI next. The specific tech stacks currently benefitting most from Raygun CLI are JavaScript/TypeScript, Flutter, and Android, but be assured that there is something in it for everyone.

1. Deployment management

One of the general and stack-independent core features of Raygun CLI is its ability to manage deployment notifications. With a simple command, you can notify Raygun about new deployments:

raygun-cli deployments --api-key=YOUR_API_KEY --version=1.2.3 --token=YOUR_ACCESS_TOKEN

The above command will notify Raygun of your application’s deployment of version 1.2.3.

Why is this important for a well-functioning error monitoring setup?

• Deployment notifications help to associate errors with specific versions.
• You can monitor the impact of deployments on application stability.
• They keep your team informed about deployment status.

The Raygun system tracks deployments in 2 places:

The Crash Reporting dashboard shows deployments as vertical bars below the main graph. This feature makes it very easy to visually recognize potential problems with a deployment. Use the cog in the top right corner of the graph to show deployments.

The second place is the Deployments page, which you can reach from your application’s sidebar. On this screen, you’ll see a list of all your deployments and a useful graph showing your deployment frequency.

Let’s move on to the second pillar of Raygun CLI — source maps.

2. Source maps management

For JavaScript and Flutter applications, source maps are crucial for debugging and stack tracing minified code. Raygun CLI makes it easy to upload source maps:

raygun-cli sourcemap --input-map=path/to/map/index.js.map --uri=https://example.com/index.js --app-id=YOUR_APP_ID --token=YOUR_ACCESS_TOKEN

Raygun CLI supports source map uploads for both JavaScript and Flutter web projects. For JavaScript applications, you can upload individual source map files. Add –platform flutter to your CLI command for Flutter web projects.

When you upload a source map file, it will be automatically processed into the Raygun system. If you’re keen to learn more about how this works, we’ve got some great documentation available. You can also validate the format of source maps with Raygun and add, manage, and delete existing source maps through our API. For more details, check out our documentation and API specification.

3. Debug and obfuscation symbols upload

After reading about source maps, you might now think: “Huh, what are debug symbols, and how are they different from source maps?”

Debug symbols often play a role when code from stacks relying on compilation gets obfuscated and scrambled up into binaries for native or virtual machine execution. Examples are Flutter apps (which get compiled into native code for iOS/Android, etc.) and Android apps (Java and Kotlin code get compiled into JVM byte code).

Flutter has a built-in obfuscation mechanism and Android apps usually use ProGuard and R8 to achieve a similar outcome when building production- or release-grade apps.

If you want proper insights into your crashes on these platforms, debug symbols are essential for error monitoring. Raygun CLI simplifies the process of uploading these symbols.

Flutter

For Flutter, you can manage obfuscation symbols with the symbols command:

raygun-cli symbols upload --path=/path/to/symbols/file --version=1.2.3 --app-id=YOUR_APP_ID --token=YOUR_ACCESS_TOKEN

The subcommand upload uploads the file to the Raygun system and identifies it with the specified version. This feature is brand-new to Raygun and you can read more about it.

Android

For Android apps, Raygun CLI supports uploading mappings.txt files created by both ProGuard and R8 with the proguard command:

raygun-cli proguard --app-id=YOUR_APP_ID --version=1.2.3 --path=/path/to/mappings.txt --external-access-token=YOUR_EXTERNAL_ACCESS_TOKEN

We’ve got some additional documentation available that goes much deeper into how Proguard and R8 work in the context of Raygun.

Technical implementation and why we used Dart

Let’s take a brief look at how we built Raygun CLI. We used Dart, but that might not be the most obvious choice. However, Dart offers several advantages:

1. Strong type system: Dart’s robust type system helps prevent runtime errors and makes the code more maintainable.

2. Cross-platform compatibility: Being written in Dart means Raygun CLI runs on multiple platforms including Windows, macOS, and Linux. As part of our build process, we’ve started to provide pre-built binaries with version 1.0.0 on the Github Release page.

3. Modular architecture: We didn’t just want to create a simple wrapper around individual HTTP calls. Raygun CLI is designed with a clean, modular architecture so that we can extend the tool in the future for many more use cases. Some of the benefits we gain from this approach are:

   • Built-in command parsing and validation
   • Separate API communication layer
   • Specific feature implementations for separate CLI commands (deployments, source maps, symbols, ProGuard)
   • Easy and multi-faceted configuration management

4. Huge 3rd-party package ecosystem: Dart is the foundation of the Flutter framework and has been around for more than 10 years. Pub.dev offers a vast range of additional packages to make building software with Dart easier.

Getting started

So, what do you need to do to give Raygun CLI a go?

We recommend you install Raygun CLI via pub.dev, a common package manager of the Dart ecosystem.

dart pub global activate raygun_cli

You can also install it from the source repository.

Both ways require you to install Dart tooling, and if you only want to use Raygun CLI, we also offer a pre-built binary from the Github release page.

Ensure you have your Raygun API key, application ID, and the required access tokens ready. You can find these in the Raygun dashboard under application settings and in your personal account settings.

Generally, the Raygun CLI commands will provide informative output, and you will be able to see if a command was executed successfully. Some CLI commands return additional output, and we provide examples in the project’s README file.

Configuration

In all our examples above, we specified application identifiers or various access and API tokens via the command line call itself.

When you use Raygun CLI regularly, this can become quite cumbersome.

Therefore, you can configure the CLI tool in multiple ways:

• Command-line arguments: Direct parameter passing for one-off operations
• Environment variables: For CI/CD pipeline integration

In one of the next releases, we’ll add support for dedicated configuration files for storing common settings.

Future development

We’re not finished with this tool yet, and the Raygun CLI project will be actively maintained and improved:

1. Additional command-line features for other Raygun APIs
2. Improved documentation and examples
3. Better direct integration with various CI/CD platforms
4. Binary deployment for common package managers (apt, yarn, dnf, homebrew etc.)

Conclusion

Raygun CLI represents a significant step forward in making error tracking and application monitoring more accessible to developers. Bringing Raygun’s powerful features to the command line enables better integration with development workflows and automated processes.

Whether managing deployments, handling source maps, or uploading debug symbols, Raygun CLI provides a streamlined, efficient way to interact with Raygun’s services. Its cross-platform compatibility and easy integration with CI/CD pipelines make it an invaluable tool for modern development teams.

For more information, contributions, or to report issues, visit the project’s GitHub repository. We welcome feedback and contributions from the developer community to make Raygun CLI even better.

Not a Raygun customer? Try out the full Crash Reporting application free for 14 days!