> For the complete documentation index, see [llms.txt](https://docs.luciq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.luciq.ai/product-guides-and-integrations/product-guides/luciq-cli/uploading-symbol-files.md).

# Uploading Symbol Files

Upload dSYMs, ProGuard and R8 mappings, NDK symbols, source maps, and Dart symbols with the Luciq CLI, from your terminal or your CI pipeline.

To symbolicate and deobfuscate your crash reports, Luciq needs your build's symbol files. The CLI uploads all of them — for iOS, Android, React Native, and Flutter — with one consistent command shape:

```bash
luciq upload <SUBCOMMAND> FILE --slug my-app --mode production [options]
```

{% hint style="info" %}
Upload commands authenticate with your **CLI token**, exactly like the data commands — run `luciq login` once, or set `LUCIQ_AUTH_TOKEN` in CI. You don't pass an application token: Luciq resolves the app from `--slug` and `--mode`.

Uploading requires the **Mapping Files** modify permission on your role, and access to the app you're uploading to. Run `luciq apps list` to see the slugs and modes available to you.
{% endhint %}

On success the CLI prints a `✓` confirmation; on failure it prints the error and exits with a non-zero status, so a failed upload fails your CI job.

Run `luciq upload help SUBCOMMAND` to see the full options of any command.

***

## iOS

| Command                      | File   | Description      |
| ---------------------------- | ------ | ---------------- |
| `luciq upload ios-dsym FILE` | `.zip` | iOS dSYM symbols |

```bash
luciq upload ios-dsym MyApp-dSYMs.zip --slug my-app --mode production
```

## Android

| Command                             | File          | Description                              |
| ----------------------------------- | ------------- | ---------------------------------------- |
| `luciq upload android-mapping FILE` | `mapping.txt` | ProGuard/R8 mapping file                 |
| `luciq upload android-ndk FILE`     | `.zip`        | NDK `.so` shared object files (`--arch`) |

```bash
luciq upload android-mapping mapping.txt \
  --slug my-app \
  --mode production \
  --version-name 1.0.0 \
  --version-code 1
```

## React Native

| Command                                            | File           | Description                              |
| -------------------------------------------------- | -------------- | ---------------------------------------- |
| `luciq upload react-native-ios-dsym FILE`          | `.zip`         | iOS native dSYM symbols                  |
| `luciq upload react-native-ios-sourcemap FILE`     | `.json`/`.txt` | iOS JavaScript source map                |
| `luciq upload react-native-android-mapping FILE`   | `mapping.txt`  | Android native ProGuard/R8 mapping       |
| `luciq upload react-native-android-sourcemap FILE` | `.json`/`.txt` | Android JavaScript source map            |
| `luciq upload react-native-ndk FILE`               | `.zip`         | NDK `.so` shared object files (`--arch`) |

```bash
luciq upload react-native-ios-sourcemap main.jsbundle.map.json \
  --slug my-app \
  --mode production \
  --version-name 1.0.0 \
  --version-code 1
```

Source-map commands additionally accept `--codepush` to tag the upload with a CodePush label.

## Flutter

| Command                                       | File          | Description                              |
| --------------------------------------------- | ------------- | ---------------------------------------- |
| `luciq upload flutter-ios-dsym FILE`          | `.zip`        | iOS native dSYM symbols                  |
| `luciq upload flutter-ios-sourcemap FILE`     | `.zip`        | iOS Dart symbol files                    |
| `luciq upload flutter-android-mapping FILE`   | `mapping.txt` | Android native ProGuard/R8 mapping       |
| `luciq upload flutter-android-sourcemap FILE` | `.zip`        | Android Dart symbol files                |
| `luciq upload flutter-ndk FILE`               | `.zip`        | NDK `.so` shared object files (`--arch`) |

```bash
luciq upload flutter-ios-sourcemap dart-symbols-ios.zip \
  --slug my-app \
  --mode production \
  --version-name 1.0.0 \
  --version-code 1
```

***

## Options by command type

`--slug` and `--mode` are required for every upload command. The remaining options depend on the type of file:

| Command type                              | Required options                                       |
| ----------------------------------------- | ------------------------------------------------------ |
| dSYM (`*-ios-dsym`)                       | `--slug`, `--mode` only                                |
| Mapping (`*-android-mapping`)             | `--slug`, `--mode`, `--version-name`, `--version-code` |
| Source map / Dart symbols (`*-sourcemap`) | `--slug`, `--mode`, `--version-name`, `--version-code` |
| NDK (`*-ndk`)                             | `--slug`, `--mode`, `--version-name`, `--arch`         |

* `--slug`: **String** — your application slug, from `luciq apps list`.
* `--mode`: **String** — the environment the build reports to: `production`, `beta`, `staging`, `alpha`, `qa`, or `development`.
* `--version-name`: **String** — your app version name, e.g. `1.0.0`.
* `--version-code`: **String** — your app version code, e.g. `1`.
* `--arch`: **String** — the NDK architecture of the `.so` files: `armeabi-v7a`, `arm64-v8a`, `x86`, or `x86_64`. NDK commands take `--arch` instead of `--version-code`.
* `--codepush`: **String** (optional, React Native source maps only) — CodePush label for the upload.

{% hint style="warning" %}
Flutter source-map commands (`flutter-ios-sourcemap`, `flutter-android-sourcemap`) expect a **`.zip`** archive of Dart debug-symbol files, while React Native source-map commands expect a **`.json`** or **`.txt`** source map.
{% endhint %}

***

## Using it in CI

Set `LUCIQ_AUTH_TOKEN` from your CI platform's secret store, and the upload step needs no interactive login:

```bash
gem install luciq-cli
luciq upload android-mapping app/build/outputs/mapping/release/mapping.txt \
  --slug my-app \
  --mode production \
  --version-name "$VERSION_NAME" \
  --version-code "$VERSION_CODE"
```

{% hint style="warning" %}
Match `--mode` to the environment the build reports to — a TestFlight or internal build uploads to `beta`, not `production` — and match `--version-name` / `--version-code` to the build exactly. A mismatch doesn't fail the upload; the symbols simply never match a crash report.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.luciq.ai/product-guides-and-integrations/product-guides/luciq-cli/uploading-symbol-files.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.