Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fuser-guides%2Frum%2Fcli%2Frum-cli.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fuser-guides%2Frum%2Fcli%2Frum-cli.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)

# 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.

[![npm version](https://img.shields.io/npm/v/@coralogix/rum-cli.svg)](https://www.npmjs.com/package/@coralogix/rum-cli)

## Links[​](#links "Direct link to Links")

* [Changelog](https://coralogix.github.io/rum-cli/CHANGELOG.html)
* [Coralogix Real User Monitoring Docs](https://coralogix.com/docs/user-guides/rum/getting-started/real-user-monitoring.md)

## Installation[​](#installation "Direct link to 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[​](#authentication-and-permissions "Direct link to 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[​](#commands "Direct link to Commands")

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

### Web:[​](#web "Direct link to 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:[​](#react-native "Direct link to 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:[​](#ios "Direct link to 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:[​](#android "Direct link to 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:[​](#flutter--dart "Direct link to 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[​](#options "Direct link to 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[​](#release-behavior "Direct link to 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)[​](#default-no-flag "Direct link to Default (no flag)")

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

### `--override` — replace an existing release[​](#--override--replace-an-existing-release "Direct link to --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[​](#--merge--add-to-an-existing-release "Direct link to --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[​](#environments "Direct link to 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[​](#folder-size-limits "Direct link to 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[​](#integration "Direct link to Integration")

### CI Integration:[​](#ci-integration "Direct link to 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:[​](#non-ci-integration "Direct link to 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](https://www.npmjs.com/package/@coralogix/browser) |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

## Optional GitHub information[​](#optional-github-information "Direct link to 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[​](#license "Direct link to License")

This project is licensed under the MIT License. See the [LICENSE](https://github.com/coralogix/rum-cli/blob/master/LICENSE) file for details.