> 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

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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.