Open in ChatGPTOpen in Claude

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

Nothing uploads automatically on any platform. This CLI is the only upload path for all of them - the Gradle plugin and the bundler plugins do other jobs and neither sends symbols.

Each section below covers where the build leaves the artifact and what to pass to -f.

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>

Your bundler decides where the maps land, so point -f at whatever folder it wrote them to. Only files ending in .js.map are picked up.

The Coralogix bundler plugins do not upload source maps. They emit a cx-metadata.json holding the app and version, which the SDK uses to attribute a frame to a micro frontend when supportMfe: true is set. Uploading is still this command's job, with or without them.

With micro frontends, run the command once per micro frontend, passing the same application and version you gave the plugin.

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>

React Native does not emit source maps unless you ask it to.

Android:

react-native bundle [...other options...] --sourcemap-output android/app/src/main/assets/index.android.bundle.map

iOS: set SOURCEMAP_FILE in the Bundle React Native code and images build phase in Xcode.

Upload the two platforms in separate runs. The CLI works out the operating system from the file name - "android" in the name means Android, anything else means iOS - so a folder holding both platforms' maps gets all of them tagged with one operating system, and half of them will be wrong.

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>

The build leaves the mapping at:

app/build/outputs/mapping/<variant>/mapping.txt

Pass that full file path to -f, not the folder. The CLI takes the first .txt it finds, and that same directory also holds seeds.txt, usage.txt and configuration.txt - so a folder path can upload the wrong file and still report success.

The Coralogix Gradle plugin does not upload mappings; it only instruments OkHttp.

--merge is not available for this command. Use --override to replace an existing upload.

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>

Build with both flags - either one alone produces no symbols:

flutter build appbundle --release --obfuscate --split-debug-info=build/symbols

That writes one file per architecture:

app.android-arm64.symbols
app.android-arm.symbols
app.android-x64.symbols
app.ios-arm64.symbols

Do not rename them. The CLI reads the architecture out of the file name.

Upload one architecture per run, pointing -f at the file itself: the first upload plain, the rest with --merge.

Requires CLI 1.1.44 or later; the latest version is recommended.

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

Available for upload-source-maps, upload-react-native-source-maps and upload-dart-symbols only. upload-dsym and upload-proguard do not support it - use --override there instead.

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))

Verify symbolication worked

An upload that succeeds is not proof that symbolication works - the artifact still has to match the events coming in. Check it in the product rather than trusting the exit code:

1. Open Error Tracking and filter to the platform you just uploaded for.
2. Select an error from the version you uploaded, and open the Stack Trace tab.
3. Expand a thread or frame.

It worked if the frames point at your own source files with real line numbers, rather than at the bundled or stripped artifact.

Function names come back too where the artifact carries them. On JavaScript source maps the names field is optional, so a frame can show the right file and line with the function name still minified - that is a partial resolution, not a failure. dSYM, ProGuard and Dart symbols restore names as well as locations.

It did not work if the frames still show generated file names, generated line numbers or raw addresses.

Things to check when it does not resolve:

• -a / --application or -v / --version does not match the values the RUM SDK was initialized with. They have to match exactly - see Authentication and permissions.
• The upload went to a different region than the SDK reports to. See Environments.
• The artifact is from a different build than the one that produced the error.

Folder size limits

The limit applies to the gzipped payload the CLI sends, not to the size of the folder on disk, so a folder larger than the limit can still upload.

• Source maps: 200 MB
• React Native source maps: 200 MB
• ProGuard mappings: 200 MB
• dSYM files: 400 MB
• Dart symbols: 400 MB

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.