> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aient.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# @aient/sourcemaps CLI reference

> Command line options for JavaScript source maps and typed Flutter Dart AOT and Apple dSYM debug artifact uploads.

# @aient/sourcemaps CLI

Use the `upload` command from CI after generating production source maps.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
aient-sourcemaps upload <directory> --service <service> [options]
```

## Options

| Option            | Meaning                                                            |
| ----------------- | ------------------------------------------------------------------ |
| `<directory>`     | Build output directory containing `.map` files                     |
| `--api-key`, `-k` | API key, or use `AIENT_API_KEY`                                    |
| `--service`, `-s` | Runtime service name                                               |
| `--commit`, `-c`  | Git commit SHA; auto-detected from common CI env vars when omitted |
| `--pattern`       | Glob for source maps; defaults to `**/*.js.map`                    |
| `--bundle-prefix` | Optional URL/path prefix prepended to derived bundle paths         |
| `--api-url`       | Optional Aient API URL override                                    |
| `--dry-run`       | List matched files without uploading                               |
| `--concurrency`   | Maximum concurrent uploads                                         |
| `--fail-on-empty` | Exit non-zero when no source maps are found                        |

## Flutter Dart AOT and Apple dSYM debug artifacts

Current supported release: `0.3.4`.

Use the installed, lockfile-pinned binary from a release-tooling package. The
command is Node-based CI tooling; it is not a Flutter runtime dependency and does
not scan or infer native build identity from an arbitrary directory.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pnpm exec aient-sourcemaps upload-debug \
  --manifest <manifest.json> \
  --distribution <app.aab-or.ipa>
```

Manifest items may be `dart_aot_dwarf` or `apple_dsym`. Each Apple item must
point to one thin, regular Mach-O DWARF member from a dSYM bundle—not the
directory or an archive—and declare the member's exact architecture and Mach-O
UUID. The CLI re-validates those values from the file bytes before uploading.

| Option           | Meaning                                                                                         |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| `--manifest`     | Required strict snake\_case manifest v1 path                                                    |
| `--distribution` | Required authoritative AAB or IPA described by the manifest                                     |
| `AIENT_API_KEY`  | Required upload-scoped API key environment variable; keys are not accepted in command arguments |
| `--api-url`      | Optional Aient API URL, or use `AIENT_API_URL`                                                  |
| `--dry-run`      | Validate and hash local distribution/artifact bytes without network calls                       |
| `--wait`         | Rejected until Aient exposes a real processing-status receipt                                   |

See [Upload Flutter debug artifacts](../source-maps/flutter-debug-artifacts) for
the pinned installation, Android and iOS build flags, native artifact retention,
manifest schema, runtime attributes, credential boundary, and release workflow.