@sophonz/cli

한국어

Uploads the files Sophonz needs to symbolicate stack traces: web source maps, iOS dSYMs and Android R8/ProGuard mappings.

Files are kept per version of your app. Source maps belong to a web version (the browser SDK's web.version); dSYMs and mappings belong to an app version (service.version).

Install

npm install -D @sophonz/cli

Requires Node.js 20 or later.

Authentication

Create an access token in Sophonz under Settings > app > Access tokens. A token belongs to one app, so no command takes an app name.

export SOPHONZ_TOKEN=sophonz_pat_...

| Option | Environment | Default | |--------|-------------|---------| | --token | SOPHONZ_TOKEN | — | | --api-url | SOPHONZ_API_URL | https://app.sophonz.ai | | --dry-run | — | off |

Web source maps

sophonz upload-sourcemaps --path dist --web-version 2026.09.14-3

Next.js (the scripts are served from /_next/static):

sophonz upload-sourcemaps --path .next/static --url-prefix _next/static \
  --web-version "$WEB_VERSION"

• --web-version must equal what the page reports: the SDK's webVersion option, or appVersion when that is unset. Set both from the same variable in CI.
• Each map is uploaded under the path of the script that references it, read from the script's sourceMappingURL. Bundlers that give the map a different name than the script (Next.js 16 Turbopack) are handled, as are inline maps.
• Upload before or right after deploying; a trace is matched when it is opened.

iOS dSYM

sophonz upload-dsym --file "$DWARF_DSYM_FOLDER_PATH" --version 1.4.0 --build-id 120

--file takes a .dSYM bundle, a directory containing bundles (every one is zipped and sent together), or an existing zip. Traces are matched by image UUID, so frameworks with their own dSYM are covered.

Android mapping

sophonz upload-mapping --file app/build/outputs/mapping/release/mapping.txt --version 1.4.0

--type PROGUARD for a legacy ProGuard mapping. --build-id matches the app.build_id the SDK reports and can replace --version. Projects using the Sophonz Gradle plugin upload mappings automatically.

GitHub Actions

- name: Upload source maps
  env:
    SOPHONZ_TOKEN: ${{ secrets.SOPHONZ_TOKEN }}
  run: npx @sophonz/cli upload-sourcemaps --path dist --web-version "${{ env.WEB_VERSION }}"