Upload debug symbols for Kotlin Multiplatform

Install posthog-cli:

npm install -g @posthog/cli

curl --proto '=https' --tlsv1.2 -LsSf https://download.posthog.com/cli | sh
posthog-cli-update

To authenticate the CLI, call the login command. This opens your browser where you select your organization, project, and API scopes to grant:

posthog-cli login

If you are using the CLI in a CI/CD environment such as GitHub Actions, you can set environment variables to authenticate:

You can also use the --host option instead of the POSTHOG_CLI_HOST environment variable to target a different PostHog instance or region. For EU users:

posthog-cli --host https://eu.posthog.com [CMD]

If your Android release uses ProGuard or R8, apply the PostHog Android Gradle plugin to the Android application module. The plugin injects a mapping ID into the app and uploads the matching mapping file during the Gradle build.

plugins {
    id("com.android.application")
    id("com.posthog.android") version "<version>"
}

Follow the Android mappings guide for authentication options and the complete Gradle configuration.

The iOS app's dSYM files let PostHog resolve Kotlin and Swift frames. In the Xcode app target:

1. Open Build Settings and set Debug Information Format to DWARF with dSYM File for Release builds.
2. Set User Script Sandboxing (ENABLE_USER_SCRIPT_SANDBOXING) to No.
3. Add a Run Script build phase after the build phases that generate the app and dSYMs.
4. Add this script:

if [[ "${CONFIGURATION:-}" != "Release" ]]; then
    exit 0
fi

export PATH="/opt/homebrew/bin:/usr/local/bin:${HOME}/.posthog:${PATH}"
POSTHOG_CLI_PATH="${POSTHOG_CLI_PATH:-$(command -v posthog-cli)}"
if [[ -z "${POSTHOG_CLI_PATH}" ]]; then
    echo "posthog-cli was not found"
    exit 1
fi

"${POSTHOG_CLI_PATH}" dsym upload \
    --directory "${DWARF_DSYM_FOLDER_PATH}" \
    --main-dsym "${DWARF_DSYM_FILE_NAME}" \
    --release-name "${PRODUCT_BUNDLE_IDENTIFIER}" \
    --release-version "${MARKETING_VERSION}" \
    --build "${CURRENT_PROJECT_VERSION}"

5. Add this path to the build phase's Input Files:

$(DWARF_DSYM_FOLDER_PATH)/$(DWARF_DSYM_FILE_NAME)/Contents/Resources/DWARF/$(EXECUTABLE_NAME)

If your production configuration has another name, update the CONFIGURATION check. Add --include-source to the upload command if you want source code context in stack traces. See the iOS dSYM guide for troubleshooting and test-crash instructions.

For Kotlin/JS, run your production browser distribution task and locate the generated JavaScript bundle and source map. Inject PostHog metadata, upload the source map, and deploy the injected assets:

DIST_DIR="<path-to-production-assets>"
RELEASE_NAME="<application-id>"
RELEASE_VERSION="<release-version>"

posthog-cli sourcemap inject \
    --directory "${DIST_DIR}" \
    --release-name "${RELEASE_NAME}" \
    --release-version "${RELEASE_VERSION}"

posthog-cli sourcemap upload \
    --directory "${DIST_DIR}" \
    --release-name "${RELEASE_NAME}" \
    --release-version "${RELEASE_VERSION}"

The deployed JavaScript files must be the files modified by sourcemap inject. If your web target uses another output format, follow the web source map guide for the generated assets.