Official Coralogix RUM CLI

The Coralogix RUM CLI is a command-line tool designed to simplify the process of uploading RUM (Real User Monitoring) data. It provides a streamlined way to authenticate with the Coralogix API and manage source maps, dSYM files, and ProGuard mappings.

Links

• Changelog
• Coralogix Real User Monitoring Docs

Installation

To install the Coralogix RUM CLI, follow these steps:

1. Open a terminal or command prompt.
2. Run the following command to install the CLI globally:

   npm install -g @coralogix/rum-cli

3. Once installed, you can use the CLI by running coralogix-rum-cli in your terminal.

Authentication and permissions

Uploads authenticate with a Coralogix API key that has Source Mapping permissions. Those permissions let the CLI upload, replace, and manage every source mapping artifact type it handles: web source maps, React Native source maps, dSYM files, ProGuard mappings and Dart symbols.

We recommend using the source mapping permission preset, which is kept up to date with the required actions. Alternatively, create a custom API key with the necessary Source Mapping actions.

How it works:

• The API key is passed explicitly with the -k / --private-key flag.
• Permissions are validated by the Coralogix backend during upload.
• If the key is missing a required permission, the upload fails with an authorization error.
• This applies to both local usage and CI pipelines.

The -a / --application and -v / --version values must match the ones used when initializing the RUM SDK, otherwise the uploaded artifacts won't resolve against incoming events.

Commands

Here are some examples of how to use the Coralogix RUM CLI:

Web:

Upload source maps:

coralogix-rum-cli upload-source-maps -k <privateKey> -a <application> -v <version> -f <folderPath> -e <env> -c <commitHash> -n <repoName> -o <orgName>

React Native:

Upload React Native source maps:

coralogix-rum-cli upload-react-native-source-maps -k <privateKey> -a <application> -v <version> -f <folderPath> -e <env> -c <commitHash> -n <repoName> -o <orgName>

iOS:

Upload dSYM file:

coralogix-rum-cli upload-dsym -k <privateKey> -a <application> -v <version> -f <folderPath> -e <env> -c <commitHash> -n <repoName> -o <orgName>

Android:

Upload ProGuard file:

coralogix-rum-cli upload-proguard -k <privateKey> -a <application> -v <version> -f <folderPath> -e <env> -c <commitHash> -n <repoName> -o <orgName>

Flutter / Dart:

Upload Dart symbols (.symbols file):

coralogix-rum-cli upload-dart-symbols -k <privateKey> -a <application> -v <version> -f <folderPath> -e <env> -c <commitHash> -n <repoName> -o <orgName>

Options

• -k, --private-key <privateKey>: Private key to authenticate with the Coralogix API.
• -a, --application <application>: Name of the application.
• -v, --version <version>: The application version (must match the version used by the RUM SDK).
• -f, --folder-path <folderPath>: Path to the folder containing the Source Maps, dSYM file, or ProGuard mapping file.
• -e, --env <env>: Your environment (e.g., EU1, US1).
• -c, --commit-hash <commitHash>: GitHub commit hash (optional).
• -n, --repo-name <repoName>: GitHub repository name (optional).
• -o, --org-name <orgName>: GitHub organization name (optional).
• --override: Override existing files (optional).
• --merge: Merge with existing files, allowing multiple uploads to the same version (optional, only for upload-source-maps, upload-react-native-source-maps, and upload-dart-symbols).
• -h, --help: Display help.

Release behavior

Uploads are version-scoped: each application and version pair is a release. By default the CLI is strict about an existing release, and the two release flags change that.

Default (no flag)

Creates a new release, and fails if the application and version already exist.

--override — replace an existing release

Replaces all existing artifacts for the given application and version:

coralogix-rum-cli upload-source-maps --override -k <privateKey> -a <application> -v <version> -f <folderPath> -e <env>

• Deletes all previously uploaded artifacts for that version.
• Uploads only the artifacts in the current command.
• Cannot be combined with --merge - passing both fails with Cannot use multiple upload modes together: --override, --merge.
• Accepted by every upload command.

Used after one or more --merge uploads for the same version, --override removes everything previously merged — the overriding upload becomes the sole source of truth for that version.

Use it when you need to correct or fully regenerate the artifacts of an existing release.

--merge — add to an existing release

Appends artifacts to an existing release instead of failing or replacing it:

coralogix-rum-cli upload-<command> --merge -k <privateKey> -a <application> -v <version> -f <folderPath> -e <env>

• Requires that the application and version already exist; fails if they don't.
• Adds new artifacts without deleting previously uploaded data.
• Does not reconcile or deduplicate artifacts.
• Cannot be combined with --override - passing both fails with Cannot use multiple upload modes together: --override, --merge.
• Accepted by upload-source-maps, upload-react-native-source-maps and upload-dart-symbols only. upload-dsym and upload-proguard do not take it.

Use it when a release is uploaded in more than one step, for example artifacts produced by separate build steps, or a large build split into smaller uploads:

# First upload
coralogix-rum-cli upload-source-maps -k $KEY -a myapp -v 1.0.0 -f ./dist/main -e $ENV

# Second upload — appends, does not replace
coralogix-rum-cli upload-source-maps -k $KEY -a myapp -v 1.0.0 -f ./dist/lazy-chunks -e $ENV --merge

Environments

Specify the appropriate environment using the -e option:

• EU1: https://ng-api-grpc.coralogix.com:443 (eu-west-1, Ireland)
• EU2: https://ng-api-grpc.eu2.coralogix.com:443 (eu-north-1, Stockholm)
• US1: https://ng-api-grpc.coralogix.us:443 (us-east-2, Ohio)
• US2: https://ng-api-grpc.cx498.coralogix.com:443 (us-west-2, Oregon)
• US3: https://ng-api-grpc.us3.coralogix.com:443 (us-central1, Iowa)
• AP1: https://ng-api-grpc.app.coralogix.in:443 (ap-south-1, Mumbai)
• AP2: https://ng-api-grpc.coralogixsg.com:443 (ap-southeast-1, Singapore)
• AP3: https://ng-api-grpc.ap3.coralogix.com:443 (ap-southeast-3, Asia Pacific (Jakarta))

Folder Size Limits

Ensure your files do not exceed the following size limits:

• React Native Source Maps: 200MB per folder
• Source Maps: 200MB per folder
• ProGuard Files: 200MB per folder
• dSYM Files: 400MB per file
• Dart Symbols: 400MB per file

Integration

CI Integration:

To automate the upload process in your CI pipeline:

1. Create a Shell Script:

   • Name it according to the use case ( e.g., upload-source-maps.sh, upload-react-native-source-maps.sh, upload-dsym.sh, or upload-proguard.sh).

2. Template for the Script:

   #! /usr/bin/env bash
   
   # Replace these values with your actual information
   REPO_NAME="your-repo-name"
   ORG_NAME="your-github-username"
   APPLICATION="your-application-name"
   ENV="your-environment"
   FILES_PATH="your-files-path"
   PRIVATE_KEY="your-coralogix-private-key"
   VERSION="your-application-version"
   
   # Get the commit hash using git rev-parse
   COMMIT_HASH=$(git rev-parse HEAD)
   
   # Run Coralogix RUM CLI to upload the respective files
   coralogix-rum-cli upload-<command> -k "$PRIVATE_KEY" -a "$APPLICATION" -v "$VERSION" -f "$FILES_PATH" -e "$ENV" -c "$COMMIT_HASH" -n "$REPO_NAME" -o "$ORG_NAME"

   Replace <command> with source-maps, react-native-source-maps, dsym, proguard, or dart-symbols based on the file type.

Non-CI Integration:

For manual uploads, use the corresponding command in your terminal:

coralogix-rum-cli upload-<command> -k "$PRIVATE_KEY" -a "$APPLICATION" -v "$VERSION" -f "$FILES_PATH" -e "$ENV" -c "$COMMIT_HASH" -n "$REPO_NAME" -o "$ORG_NAME"

Replace <command> with one of the following as needed:

• source-maps
• react-native-source-maps
• dsym
• proguard
• dart-symbols

| IMPORTANT: The $VERSION parameter must exactly match the version specified in the SDK initialization (init) function configuration in your Coralogix SDK for Browsers | |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

Optional GitHub Information

You can provide additional GitHub-related options to enhance source map management:

• -c, --commit-hash <commitHash>: The commit hash associated with the source maps.
• -n, --repo-name <repoName>: The repository name where the source code is hosted.
• -o, --org-name <orgName>: The organization user associated with the repository.

These options are optional but can improve issue tracking within Coralogix RUM.

License

This project is licensed under the MIT License. See the LICENSE file for details.