> 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 --app-token YOUR_APP_TOKEN [options]
```

{% hint style="info" %}
Upload commands authenticate with your **app token** — the same token you use to initialize the Luciq SDK — not your personal CLI token. That means your CI pipeline can upload symbol files without running `luciq login`.
{% 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 --app-token YOUR_APP_TOKEN
```

## 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 \
  --app-token YOUR_APP_TOKEN \
  --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 \
  --app-token YOUR_APP_TOKEN \
  --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 \
  --app-token YOUR_APP_TOKEN \
  --version-name 1.0.0 \
  --version-code 1
```

***

## Options by command type

`--app-token` is required for every upload command. The remaining options depend on the type of file:

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

* `--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

Because uploads only need the app token, a minimal CI step looks like:

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

Store the app token as a CI secret and export it into the job's environment.


---

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