diff --git a/docs/cli/update.md b/docs/cli/update.md
index 3dddfbaf51..3c1bb9266d 100644
--- a/docs/cli/update.md
+++ b/docs/cli/update.md
@@ -10,6 +10,86 @@ To update a specific dependency to the latest version:
 $ bun update [package]
 ```
 
+## `--interactive`
+
+For a more controlled update experience, use the `--interactive` flag to select which packages to update:
+
+```sh
+$ bun update --interactive
+$ bun update -i
+```
+
+This launches an interactive terminal interface that shows all outdated packages with their current and target versions. You can then select which packages to update.
+
+### Interactive Interface
+
+The interface displays packages grouped by dependency type:
+
+```
+? Select packages to update - Space to toggle, Enter to confirm, a to select all, n to select none, i to invert, l to toggle latest
+
+  dependencies                Current  Target   Latest
+    □ react                   17.0.2   18.2.0   18.3.1
+    □ lodash                  4.17.20  4.17.21  4.17.21
+
+  devDependencies             Current  Target   Latest
+    □ typescript              4.8.0    5.0.0    5.3.3
+    □ @types/node             16.11.7  18.0.0   20.11.5
+
+  optionalDependencies        Current  Target   Latest
+    □ some-optional-package   1.0.0    1.1.0    1.2.0
+```
+
+**Sections:**
+
+- Packages are grouped under section headers: `dependencies`, `devDependencies`, `peerDependencies`, `optionalDependencies`
+- Each section shows column headers aligned with the package data
+
+**Columns:**
+
+- **Package**: Package name (may have suffix like ` dev`, ` peer`, ` optional` for clarity)
+- **Current**: Currently installed version
+- **Target**: Version that would be installed (respects semver constraints)
+- **Latest**: Latest available version
+
+### Keyboard Controls
+
+**Selection:**
+
+- **Space**: Toggle package selection
+- **Enter**: Confirm selections and update
+- **a/A**: Select all packages
+- **n/N**: Select none
+- **i/I**: Invert selection
+
+**Navigation:**
+
+- **↑/↓ Arrow keys** or **j/k**: Move cursor
+- **l/L**: Toggle between target and latest version for current package
+
+**Exit:**
+
+- **Ctrl+C** or **Ctrl+D**: Cancel without updating
+
+### Visual Indicators
+
+- **☑** Selected packages (will be updated)
+- **□** Unselected packages
+- **>** Current cursor position
+- **Colors**: Red (major), yellow (minor), green (patch) version changes
+- **Underlined**: Currently selected update target
+
+### Package Grouping
+
+Packages are organized in sections by dependency type:
+
+- **dependencies** - Regular runtime dependencies
+- **devDependencies** - Development dependencies
+- **peerDependencies** - Peer dependencies
+- **optionalDependencies** - Optional dependencies
+
+Within each section, individual packages may have additional suffixes (` dev`, ` peer`, ` optional`) for extra clarity.
+
 ## `--latest`
 
 By default, `bun update` will update to the latest version of a dependency that satisfies the version range specified in your `package.json`.
@@ -20,6 +100,8 @@ To update to the latest version, regardless of if it's compatible with the curre
 $ bun update --latest
 ```
 
+In interactive mode, you can toggle individual packages between their target version (respecting semver) and latest version using the **l** key.
+
 For example, with the following `package.json`:
 
 ```json