diff --git a/docs/cli/code-mappings.mdx b/docs/cli/code-mappings.mdx
new file mode 100644
index 00000000000000..079dce24e2882f
--- /dev/null
+++ b/docs/cli/code-mappings.mdx
@@ -0,0 +1,59 @@
+---
+title: "Code Mappings"
+sidebar_order: 5
+description: "Upload code mappings to Sentry via the CLI. Code mappings link stack trace paths to source code paths in your repository, enabling source context, suspect commits, and code owners."
+---
+_Available in version 3.3.4 of Sentry CLI_
+
+Code mappings link stack trace paths to source code paths in your repository. They enable features like [source context](/platforms/java/source-context/), [suspect commits](/product/issues/suspect-commits/), [stack trace linking](/organization/integrations/source-code-mgmt/github/#stack-trace-linking), and [code owners](/product/issues/ownership-rules/).
+
+You can [manage code mappings through the Sentry web UI](/product/issues/suspect-commits/#set-up-code-mappings), or upload them in bulk using Sentry CLI. It is also possible to upload code mappings automatically in your CI process to keep them in sync with your repository structure.
+
+## Permissions
+
+Sentry CLI requires an [Organization Token](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/) with the `org:ci` scope to upload code mappings.
+
+## Upload Code Mappings
+
+Use the `sentry-cli code-mappings upload` command to upload code mappings:
+
+```bash
+sentry-cli code-mappings upload ./mappings.json
+```
+
+Run `sentry-cli code-mappings upload --help` to see all available options.
+
+### JSON File Format
+
+The input file should be a JSON array of mapping objects, each with a `stackRoot` and `sourceRoot`:
+
+- **stackRoot**: The path prefix as it appears in stack traces (e.g. `io/sentry/android/core` for Java, `src/` for Python/JS).
+- **sourceRoot**: The corresponding path in your repository where the source code lives.
+
+Multiple mappings can share the same `stackRoot` if they point to different `sourceRoot` paths. This is useful for monorepos where the same package prefix exists in multiple modules. Sentry evaluates mappings from most specific to least specific, using the first one that resolves to a real file in the repository.
+
+#### Example
+
+The following example is based on the [getsentry/sentry-java](https://github.com/getsentry/sentry-java) monorepo, which has multiple modules sharing the `io/sentry` package prefix:
+
+```json {filename:mappings.json}
+[
+ {
+ "stackRoot": "io/sentry/android/core",
+ "sourceRoot": "sentry-android-core/src/main/java/io/sentry/android/core"
+ },
+ {
+ "stackRoot": "io/sentry/opentelemetry",
+ "sourceRoot": "sentry-opentelemetry/sentry-opentelemetry-core/src/main/java/io/sentry/opentelemetry"
+ },
+ {
+ "stackRoot": "io/sentry/opentelemetry",
+ "sourceRoot": "sentry-opentelemetry/sentry-opentelemetry-bootstrap/src/main/java/io/sentry/opentelemetry"
+ },
+ {
+ "stackRoot": "io/sentry",
+ "sourceRoot": "sentry/src/main/java/io/sentry"
+ }
+]
+```
+
diff --git a/docs/cli/index.mdx b/docs/cli/index.mdx
index 01055f33701362..9b56d5d463c9e5 100644
--- a/docs/cli/index.mdx
+++ b/docs/cli/index.mdx
@@ -18,6 +18,6 @@ These docs cover `sentry-cli`, used in CI/CD pipelines and build processes. If y
-For certain actions, you can use the `sentry-cli` command line executable. It can connect to the Sentry API and manage some data for your projects. It’s primarily used for managing debug information files for iOS, Android as well as release and source maps management for other platforms.
+For certain actions, you can use the `sentry-cli` command line executable. It can connect to the Sentry API and manage some data for your projects. It’s primarily used for managing debug information files for iOS, Android, release and source maps management, as well as code mappings for other platforms.
diff --git a/docs/organization/integrations/source-code-mgmt/github/index.mdx b/docs/organization/integrations/source-code-mgmt/github/index.mdx
index 18a9486460a75c..525a5ea6db919d 100644
--- a/docs/organization/integrations/source-code-mgmt/github/index.mdx
+++ b/docs/organization/integrations/source-code-mgmt/github/index.mdx
@@ -377,7 +377,7 @@ By default, this feature is automatically enabled once your GitHub integration h
-Sentry will automatically try to set up code mappings on JavaScript, Python, Java, PHP, Ruby, Go, C#, and Kotlin for organizations with the GitHub integration installed. If your project uses a different SDK, you can add code mappings manually.
+Sentry will automatically try to set up code mappings on JavaScript, Python, Java, PHP, Ruby, Go, C#, and Kotlin for organizations with the GitHub integration installed. If your project uses a different SDK, you can add code mappings manually. You can also [upload code mappings in bulk via the CLI](/cli/code-mappings/).
diff --git a/docs/platforms/java/common/source-context/index.mdx b/docs/platforms/java/common/source-context/index.mdx
index fa33aaeb874dd3..b7a06bb36decd1 100644
--- a/docs/platforms/java/common/source-context/index.mdx
+++ b/docs/platforms/java/common/source-context/index.mdx
@@ -10,7 +10,7 @@ og_image: /og-images/platforms-java-common-source-context.png
## Setting Up Code Mappings
-To use suspect commits and stack trace linking, you'll need to set up a code mapping. This is a mapping between the source code in your repository and the source code in your stack traces. You can find information on how to set up code mappings in our [Set Up Code Mappings](/product/issues/suspect-commits/#2-set-up-code-mappings) docs.
+To use suspect commits and stack trace linking, you'll need to set up a code mapping. This is a mapping between the source code in your repository and the source code in your stack traces. You can [set up code mappings manually in the Sentry UI](/product/issues/suspect-commits/#set-up-code-mappings) or [upload code mappings in bulk via Sentry CLI](/cli/code-mappings/). We recommend using the CLI if your project has many modules.
Use the following steps to determine the correct **Stack Trace Root** **Source Code Root** while setting up your code mapping:
diff --git a/docs/product/issues/suspect-commits/index.mdx b/docs/product/issues/suspect-commits/index.mdx
index e0bd8a27a7204c..0ca9dcbb27f0a0 100644
--- a/docs/product/issues/suspect-commits/index.mdx
+++ b/docs/product/issues/suspect-commits/index.mdx
@@ -45,6 +45,8 @@ In [sentry.io](https://sentry.io):
Sentry will automatically try to set up code mappings on JavaScript, Python, Java, PHP, Ruby, Go, C#, and Kotlin projects for organizations with the GitHub integration installed. However, you can still manually add code mappings if you choose to do so. Support for other languages and other source code integrations are planned.
+You can also upload code mappings in bulk using the [Sentry CLI](/cli/code-mappings/).
+
1. Go to **Settings > Integrations > [Integration] > Configurations**.