RUM CLI

The Coralogix RUM CLI is a command-line interface tool that simplifies the process of uploading Real User Monitoring artifacts across Web and mobile platforms. This CLI tool provides an easy and efficient way to authenticate with the Coralogix API, specify the application and release information, and traverse a folder to upload the relevant source map files.

What is the RUM CLI

The Coralogix RUM CLI is a command-line tool for uploading and managing RUM artifacts, including Web source maps, React Native source maps, iOS dSYM files, and Android ProGuard mappings. It provides a consistent interface for authentication, artifact upload, replacement, and CI integration across platforms.

Supported artifacts

• Web source maps
• React Native source maps
• iOS dSYM files
• Android ProGuard mappings

Install the RUM CLI

npm install -g @coralogix/rum-cli

Run the CLI with:

coralogix-rum-cli

Authentication and permissions

Use a Coralogix API key with Source Mapping permissions. The application name and version must match the values used in the corresponding RUM SDK initialization.

API key requirements

When uploading artifacts with the RUM CLI, the API key must include Source Mapping permissions. These permissions allow the CLI to upload, replace, and manage source mapping artifacts such as source maps, dSYM files, and ProGuard mappings.

We recommend using a permission preset for source mapping, as presets are automatically kept up to date with required actions. Alternatively, you can create a custom API key with the necessary Source Mapping actions.

How authentication works

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

For instructions on creating API keys and managing permissions, see the Coralogix API Keys documentation.

Environments

Specify the environment using -e (for example: EU1, US1). Use the environment that matches your Coralogix domain.

Before uploading artifacts, ensure they are generated correctly in your application build process. For framework-specific guidance, see:

• Source Maps: JavaScript
• Source Maps: React Native

Upload artifacts

Web source maps

coralogix-rum-cli upload-source-maps -k <API_KEY> -a <APPLICATION> -v <VERSION> -f <PATH> -e <ENV>

React Native source maps

coralogix-rum-cli upload-react-native-source-maps -k <API_KEY> -a <APPLICATION> -v <VERSION> -f <PATH> -e <ENV>

iOS dSYM

coralogix-rum-cli upload-dsym -k <API_KEY> -a <APPLICATION> -v <VERSION> -f <PATH> -e <ENV>

Android ProGuard

coralogix-rum-cli upload-proguard -k <API_KEY> -a <APPLICATION> -v <VERSION> -f <PATH> -e <ENV>

Release behavior flags

By default, artifact uploads are version-scoped. Each application and version pair represents a release.

If a release already exists, the CLI enforces strict behavior unless a release flag is provided.

Default behavior (no flag)

Creates a new release.

Fails if the specified application and version already exist.

Replace existing release (--override)

The --override flag replaces all existing artifacts for the specified application and version.

coralogix-rum-cli upload-source-maps--override-k <API_KEY>-a <APPLICATION>-v <VERSION>-f <PATH>-e <ENV>

Behavior:

• Deletes all previously uploaded artifacts for the version
• Uploads only the artifacts provided in the current command
• Cannot be combined with --merge

This flag is currently supported only for Web source maps uploaded using the upload-source-maps command.

If --override is used after one or more --merge uploads for the same version, all previously merged artifacts are removed. The overridden upload becomes the sole source of truth for that version.

Use this flag when you need to correct or fully regenerate artifacts for an existing release.

Merge into existing release (--merge)

The --merge flag enables incremental uploads to an existing release. Instead of failing or replacing data, it appends new artifacts to the specified application and version.

coralogix-rum-cli upload-<command>--merge-k <API_KEY>-a <APPLICATION>-v <VERSION>-f <PATH>-e <ENV>

Behavior:

• Requires that the specified application and version already exist
• Adds new artifacts to the existing release without deleting previously uploaded data
• Does not reconcile or deduplicate artifacts automatically
• Cannot be combined with --override

If the specified application and version do not already exist, the --merge command fails.

Supported commands:

• upload-source-maps
• upload-react-native-source-maps
• upload-dsym
• upload-proguard

Use this when:

• Uploading artifacts from multiple build steps
• Splitting large builds into smaller uploads
• Uploading iOS dSYM and Android ProGuard separately for the same version

Example:

# First upload
coralogix-rum-cli upload-source-maps-k$KEY-a myapp-v1.0.0-f ./dist/main

# Second upload (appends, does not replace)
coralogix-rum-cli upload-source-maps-k$KEY-a myapp-v1.0.0-f ./dist/lazy-chunks--merge

CI integration

Use the CLI after your build step and before deployment so symbolication is available immediately after release. The same commands apply in CI and non-CI environments.

Limits

• Source maps (Web, RN): 200 MB per folder
• ProGuard: 200 MB per folder
• dSYM: 400 MB per file

Additional Resources