Merge branch 'main' into sdlsdl

9 files changed, 423 insertions, 265 deletions

diff --git a/docs/cli/add.md b/docs/cli/add.md
new file mode 100644
index 000000000..4b555d5a6
--- /dev/null
+++ b/docs/cli/add.md
@@ -0,0 +1,155 @@
+To add a particular package:
+
+```bash
+$ bun add preact
+```
+
+To specify a version, version range, or tag:
+
+```bash
+$ bun add zod@3.20.0
+$ bun add zod@^3.0.0
+$ bun add zod@latest
+```
+
+## `--dev`
+
+{% callout %}
+**Alias** — `--development`, `-d`, `-D`
+{% /callout %}
+
+To add a package as a dev dependency (`"devDependencies"`):
+
+```bash
+$ bun add --dev @types/react
+$ bun add -d @types/react
+```
+
+## `--optional`
+
+To add a package as an optional dependency (`"optionalDependencies"`):
+
+```bash
+$ bun add --optional lodash
+```
+
+## `--exact`
+
+To add a package and pin to the resolved version, use `--exact`. This will resolve the version of the package and add it to your `package.json` with an exact version number instead of a version range.
+
+```bash
+$ bun add react --exact
+$ bun add react -E
+```
+
+This will add the following to your `package.json`:
+
+```jsonc
+{
+  "dependencies": {
+    // without --exact
+    "react": "^18.2.0", // this matches >= 18.2.0 < 19.0.0
+
+    // with --exact
+    "react": "18.2.0" // this matches only 18.2.0 exactly
+  }
+}
+```
+
+To view a complete list of options for this command:
+
+```bash
+$ bun add --help
+```
+
+## `--global`
+
+{% callout %}
+**Note** — This would not modify package.json of your current project folder.
+**Alias** - `bun add --global`, `bun add -g`, `bun install --global` and `bun install -g`
+{% /callout %}
+
+To install a package globally, use the `-g`/`--global` flag. This will not modify the `package.json` of your current project. Typically this is used for installing command-line tools.
+
+```bash
+$ bun add --global cowsay # or `bun add -g cowsay`
+$ cowsay "Bun!"
+ ______
+< Bun! >
+ ------
+        \   ^__^
+         \  (oo)\_______
+            (__)\       )\/\
+                ||----w |
+                ||     ||
+```
+
+{% details summary="Configuring global installation behavior" %}
+
+```toml
+[install]
+# where `bun add --global` installs packages
+globalDir = "~/.bun/install/global"
+
+# where globally-installed package bins are linked
+globalBinDir = "~/.bun/bin"
+```
+
+{% /details %}
+
+## Trusted dependencies
+
+Unlike other npm clients, Bun does not execute arbitrary lifecycle scripts for installed dependencies, such as `postinstall`. These scripts represent a potential security risk, as they can execute arbitrary code on your machine.
+
+To tell Bun to allow lifecycle scripts for a particular package, add the package to `trustedDependencies` in your package.json.
+
+```json-diff
+  {
+    "name": "my-app",
+    "version": "1.0.0",
++   "trustedDependencies": ["my-trusted-package"]
+  }
+```
+
+Bun reads this field and will run lifecycle scripts for `my-trusted-package`.
+
+<!-- Bun maintains an allow-list of popular packages containing `postinstall` scripts that are known to be safe. To run lifecycle scripts for packages that aren't on this list, add the package to `trustedDependencies` in your package.json. -->
+
+## Git dependencies
+
+To add a dependency from a git repository:
+
+```bash
+$ bun add git@github.com:moment/moment.git
+```
+
+Bun supports a variety of protocols, including [`github`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#github-urls), [`git`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#git-urls-as-dependencies), `git+ssh`, `git+https`, and many more.
+
+```json
+{
+  "dependencies": {
+    "dayjs": "git+https://github.com/iamkun/dayjs.git",
+    "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21",
+    "moment": "git@github.com:moment/moment.git",
+    "zod": "github:colinhacks/zod"
+  }
+}
+```
+
+## Tarball dependencies
+
+A package name can correspond to a publicly hosted `.tgz` file. During installation, Bun will download and install the package from the specified tarball URL, rather than from the package registry.
+
+```sh
+$ bun add zod@https://registry.npmjs.org/zod/-/zod-3.21.4.tgz
+```
+
+This will add the following line to your `package.json`:
+
+```json#package.json
+{
+  "dependencies": {
+    "zod": "https://registry.npmjs.org/zod/-/zod-3.21.4.tgz"
+  }
+}
+```
diff --git a/docs/cli/create.md b/docs/cli/bun-create.md
index d59912f2b..c5cc602b6 100644
--- a/docs/cli/create.md
+++ b/docs/cli/bun-create.md
@@ -1,56 +1,55 @@
-## `bun init`
+{% callout %}
+**Note** — You don’t need `bun create` to use Bun. You don’t need any configuration at all. This command exists to make getting started a bit quicker and easier.
+{% /callout %}
 
-Scaffold an empty project with `bun init`. It's an interactive tool.
+Template a new Bun project with `bun create`. This is a flexible command that can be used to create a new project with a `create-<template>` npm package, a GitHub repo, or a local template.
 
-```bash
-$ bun init
-bun init helps you get started with a minimal project and tries to
-guess sensible defaults. Press ^C anytime to quit.
+If you're looking to create a brand new empty project, use [`bun init`](/docs/cli/init).
+
+## From `npm`
 
-package name (quickstart):
-entry point (index.ts):
+```sh
+$ bun create <template> [<destination>]
+```
 
-Done! A package.json file was saved in the current directory.
- + index.ts
- + .gitignore
- + tsconfig.json (for editor auto-complete)
- + README.md
+Assuming you don't have a [local template](#from-a-local-template) with the same name, this command will download and execute the `create-<template>` package from npm. The following two commands will behave identically:
 
-To get started, run:
-  bun run index.ts
+```sh
+$ bun create remix
+$ bunx create-remix
 ```
 
-Press `enter` to accept the default answer for each prompt, or pass the `-y` flag to auto-accept the defaults.
+Refer to the documentation of the associated `create-<template>` package for complete documentation and usage instructions.
 
-## `bun create`
+## From GitHub
 
-Template a new Bun project with `bun create`.
+This will download the contents of the GitHub repo to disk.
 
 ```bash
-$ bun create <template> <destination>
+$ bun create <user>/<repo>
+$ bun create github.com/<user>/<repo>
 ```
 
-{% callout %}
-**Note** — You don’t need `bun create` to use Bun. You don’t need any configuration at all. This command exists to make getting started a bit quicker and easier.
-{% /callout %}
-
-A template can take a number of forms:
+Optionally specify a name for the destination folder. If no destination is specified, the repo name will be used.
 
 ```bash
-$ bun create <template>         # an official template (remote)
-$ bun create <username>/<repo>  # a GitHub repo (remote)
-$ bun create <local-template>   # a custom template (local)
+$ bun create <user>/<repo> mydir
+$ bun create github.com/<user>/<repo> mydir
 ```
 
-Running `bun create` performs the following steps:
+Bun will perform the following steps:
 
-- Download the template (remote templates only)
-- Copy all template files into the destination folder. By default Bun will _not overwrite_ any existing files. Use the `--force` flag to overwrite existing files.
+- Download the template
+- Copy all template files into the destination folder
 - Install dependencies with `bun install`.
 - Initialize a fresh Git repo. Opt out with the `--no-git` flag.
 - Run the template's configured `start` script, if defined.
 
-<!-- ## Official templates
+{% callout %}
+By default Bun will _not overwrite_ any existing files. Use the `--force` flag to overwrite existing files.
+{% /callout %}
+
+<!-- ### Official templates
 
 The following official templates are available.
 
@@ -75,7 +74,7 @@ Welcome to bun! Create a new project by pasting any of the following:
 ⚡️ **Speed** — At the time of writing, `bun create react app` runs ~11x faster on a M1 Macbook Pro than `yarn create react-app app`.
 {% /callout %} -->
 
-## GitHub repos
+<!-- ### GitHub repos
 
 A template of the form `<username>/<repo>` will be downloaded from GitHub.
 
@@ -90,9 +89,9 @@ $ bun create github.com/ahfarmer/calculator ./myapp
 $ bun create https://github.com/ahfarmer/calculator ./myapp
 ```
 
-Bun installs the files as they currently exist current default branch (usually `main`). Unlike `git clone` it doesn't download the commit history or configure a remote.
+Bun installs the files as they currently exist current default branch (usually `main` or `master`). Unlike `git clone` it doesn't download the commit history or configure a remote. -->
 
-## Local templates
+## From a local template
 
 {% callout %}
 **⚠️ Warning** — Unlike remote templates, running `bun create` with a local template will delete the entire destination folder if it already exists! Be careful.
@@ -124,26 +123,9 @@ Then, create a `package.json` file in that directory with the following contents
 
 You can run `bun create foo` elsewhere on your file system to verify that Bun is correctly finding your local template.
 
-{% table %}
+#### Setup logic
 
----
-
-- `postinstall`
-- runs after installing dependencies
-
----
-
-- `preinstall`
-- runs before installing dependencies
-
-<!-- ---
-
-- `start`
-- a command to auto-start the application -->
-
-{% /table %}
-
-Each of these can correspond to a string or array of strings. An array of commands will be executed in order. Here is an example:
+You can specify pre- and post-install setup scripts in the `"bun-create"` section of your local template's `package.json`.
 
 ```json
 {
@@ -162,7 +144,23 @@ Each of these can correspond to a string or array of strings. An array of comman
 }
 ```
 
-When cloning a template, `bun create` will automatically remove the `"bun-create"` section from `package.json` before writing it to the destination folder.
+The following fields are supported. Each of these can correspond to a string or array of strings. An array of commands will be executed in order.
+
+{% table %}
+
+---
+
+- `postinstall`
+- runs after installing dependencies
+
+---
+
+- `preinstall`
+- runs before installing dependencies
+
+{% /table %}
+
+After cloning a template, `bun create` will automatically remove the `"bun-create"` section from `package.json` before writing it to the destination folder.
 
 ## Reference
 
diff --git a/docs/cli/bun-install.md b/docs/cli/bun-install.md
index 3efe2da7f..0cbc21e1d 100644
--- a/docs/cli/bun-install.md
+++ b/docs/cli/bun-install.md
@@ -21,7 +21,7 @@ Configuring with `bunfig.toml` is optional. Bun tries to be zero configuration i
 
 # Scope name      The value can be a URL string or an object
 "@mybigcompany" = { token = "123456", url = "https://registry.mybigcompany.com" }
-# URL is optional and fallsback to the default registry
+# URL is optional and falls back to the default registry
 
 # The "@" in the scope is optional
 mybigcompany2 = { token = "123456" }
diff --git a/docs/cli/bun-init.md b/docs/cli/init.md
index bc51614e3..f17c8e1b7 100644
--- a/docs/cli/bun-init.md
+++ b/docs/cli/init.md
@@ -1,3 +1,27 @@
+Scaffold an empty Bun project with the interactive `bun init` command.
+
+```bash
+$ bun init
+bun init helps you get started with a minimal project and tries to
+guess sensible defaults. Press ^C anytime to quit.
+
+package name (quickstart):
+entry point (index.ts):
+
+Done! A package.json file was saved in the current directory.
+ + index.ts
+ + .gitignore
+ + tsconfig.json (for editor auto-complete)
+ + README.md
+
+To get started, run:
+  bun run index.ts
+```
+
+Press `enter` to accept the default answer for each prompt, or pass the `-y` flag to auto-accept the defaults.
+
+{% details summary="How `bun init` works" %}
+
 `bun init` is a quick way to start a blank project with Bun. It guesses with sane defaults and is non-destructive when run multiple times.
 
 ![Demo](https://user-images.githubusercontent.com/709451/183006613-271960a3-ff22-4f7c-83f5-5e18f684c836.gif)
@@ -13,6 +37,4 @@ If you pass `-y` or `--yes`, it will assume you want to continue without asking
 
 At the end, it runs `bun install` to install `bun-types`.
 
-#### How is `bun init` different than `bun create`?
-
-`bun init` is for blank projects. `bun create` applies templates.
+{% /details %}
diff --git a/docs/cli/install.md b/docs/cli/install.md
index 9aafae301..573a6f106 100644
--- a/docs/cli/install.md
+++ b/docs/cli/install.md
@@ -23,41 +23,19 @@ sudo apt install --install-recommends linux-generic-hwe-20.04
 
 {% /details %}
 
-## `bun install`
-
 To install all dependencies of a project:
 
 ```bash
 $ bun install
 ```
 
-On Linux, `bun install` tends to install packages 20-100x faster than `npm install`. On macOS, it's more like 4-80x.
-
-![package install benchmark](https://user-images.githubusercontent.com/709451/147004342-571b6123-17a9-49a2-8bfd-dcfc5204047e.png)
-
 Running `bun install` will:
 
 - **Install** all `dependencies`, `devDependencies`, and `optionalDependencies`. Bun does not install `peerDependencies` by default.
 - **Run** your project's `{pre|post}install` and `{pre|post}prepare` scripts at the appropriate time. For security reasons Bun _does not execute_ lifecycle scripts of installed dependencies.
 - **Write** a `bun.lockb` lockfile to the project root.
 
-To install in production mode (i.e. without `devDependencies` or `optionalDependencies`):
-
-```bash
-$ bun install --production
-```
-
-To install with reproducible dependencies, use `--frozen-lockfile`. If your `package.json` disagrees with `bun.lockb`, Bun will exit with an error. This is useful for production builds and CI environments.
-
-```bash
-$ bun install --frozen-lockfile
-```
-
-To perform a dry run (i.e. don't actually install anything):
-
-```bash
-$ bun install --dry-run
-```
+## Logging
 
 To modify logging verbosity:
 
@@ -66,86 +44,59 @@ $ bun install --verbose # debug logging
 $ bun install --silent  # no logging
 ```
 
-{% details summary="Configuring behavior" %}
-The default behavior of `bun install` can be configured in `bunfig.toml`:
-
-```toml
-[install]
-
-# whether to install optionalDependencies
-optional = true
+## Lifecycle scripts
 
-# whether to install devDependencies
-dev = true
-
-# whether to install peerDependencies
-peer = false
-
-# equivalent to `--production` flag
-production = false
-
-# equivalent to `--frozen-lockfile` flag
-frozenLockfile = false
-
-# equivalent to `--dry-run` flag
-dryRun = false
-```
-
-{% /details %}
+Unlike other npm clients, Bun does not execute arbitrary lifecycle scripts like `postinstall` for installed dependencies. Executing arbitrary scripts represents a potential security risk.
 
-## `bun add`
-
-To add a particular package:
-
-```bash
-$ bun add preact
-```
-
-To specify a version, version range, or tag:
-
-```bash
-$ bun add zod@3.20.0
-$ bun add zod@^3.0.0
-$ bun add zod@latest
-```
-
-To add a package as a dev dependency (`"devDependencies"`):
+To tell Bun to allow lifecycle scripts for a particular package, add the package to `trustedDependencies` in your package.json.
 
-```bash
-$ bun add --dev @types/react
-$ bun add -d @types/react
+```json-diff
+  {
+    "name": "my-app",
+    "version": "1.0.0",
++   "trustedDependencies": ["my-trusted-package"]
+  }
 ```
 
-To add a package as an optional dependency (`"optionalDependencies"`):
+Then re-install the package. Bun will read this field and run lifecycle scripts for `my-trusted-package`.
 
-```bash
-$ bun add --optional lodash
-```
+## Workspaces
 
-To add a package and pin to the resolved version, use `--exact`. This will resolve the version of the package and add it to your `package.json` with an exact version number instead of a version range.
+Bun supports `"workspaces"` in package.json. For complete documentation refer to [Package manager > Workspaces](/docs/install/workspaces).
 
-```bash
-$ bun add react --exact
+```json#package.json
+{
+  "name": "my-app",
+  "version": "1.0.0",
+  "workspaces": ["packages/*"],
+  "dependencies": {
+    "preact": "^10.5.13"
+  }
+}
 ```
 
-This will add the following to your `package.json`:
+## Overrides and resolutions
 
-```jsonc
-{
-  "dependencies": {
-    // without --exact
-    "react": "^18.2.0", // this matches >= 18.2.0 < 19.0.0
+Bun supports npm's `"overrides"` and Yarn's `"resolutions"` in `package.json`. These are mechanisms for specifying a version range for _metadependencies_—the dependencies of your dependencies. Refer to [Package manager > Overrides and resolutions](/docs/install/overrides) for complete documentation.
 
-    // with --exact
-    "react": "18.2.0" // this matches only 18.2.0 exactly
+```json-diff#package.json
+  {
+    "name": "my-app",
+    "dependencies": {
+      "foo": "^2.0.0"
+    },
++   "overrides": {
++     "bar": "~4.4.0"
++   }
   }
-}
 ```
 
-To install a package globally:
+## Global packages
+
+To install a package globally, use the `-g`/`--global` flag. Typically this is used for installing command-line tools.
 
 ```bash
-$ bun add --global cowsay # or `bun add -g cowsay`
+$ bun install --global cowsay # or `bun install -g cowsay`
 $ cowsay "Bun!"
  ______
 < Bun! >
@@ -157,159 +108,75 @@ $ cowsay "Bun!"
                 ||     ||
 ```
 
-{% details summary="Configuring global installation behavior" %}
-
-```toml
-[install]
-# where `bun install --global` installs packages
-globalDir = "~/.bun/install/global"
+## Production mode
 
-# where globally-installed package bins are linked
-globalBinDir = "~/.bun/bin"
-```
-
-{% /details %}
-To view a complete list of options for a given command:
+To install in production mode (i.e. without `devDependencies` or `optionalDependencies`):
 
 ```bash
-$ bun add --help
+$ bun install --production
 ```
 
-## `bun remove`
-
-To remove a dependency:
+For reproducible installs, use `--frozen-lockfile`. This will install the exact versions of each package specified in the lockfile. If your `package.json` disagrees with `bun.lockb`, Bun will exit with an error. The lockfile will not be updated.
 
 ```bash
-$ bun remove preact
-```
-
-## `bun update`
-
-To update all dependencies to the latest version _that's compatible with the version range specified in your `package.json`_:
-
-```sh
-$ bun update
+$ bun install --frozen-lockfile
 ```
 
-This will not edit your `package.json`. There's currently no command to force-update all dependencies to the latest version regardless version ranges.
-
-## `bun link`
+For more information on Bun's binary lockfile `bun.lockb`, refer to [Package manager > Lockfile](/docs/install/lockfile).
 
-Use `bun link` in a local directory to register the current package as a "linkable" package.
+## Dry run
 
-```bash
-$ cd /path/to/cool-pkg
-$ cat package.json
-{
-  "name": "cool-pkg",
-  "version": "1.0.0"
-}
-$ bun link
-bun link v1.x (7416672e)
-Success! Registered "cool-pkg"
-
-To use cool-pkg in a project, run:
-  bun link cool-pkg
-
-Or add it in dependencies in your package.json file:
-  "cool-pkg": "link:cool-pkg"
-```
-
-This package can now be "linked" into other projects using `bun link cool-pkg`. This will create a symlink in the `node_modules` directory of the target project, pointing to the local directory.
+To perform a dry run (i.e. don't actually install anything):
 
 ```bash
-$ cd /path/to/my-app
-$ bun link cool-pkg
-```
-
-In addition, the `--save` flag can be used to add `cool-pkg` to the `dependencies` field of your app's package.json with a special version specifier that tells Bun to load from the registered local directory instead of installing from `npm`:
-
-```json-diff
-  {
-    "name": "my-app",
-    "version": "1.0.0",
-    "dependencies": {
-+     "cool-pkg": "link:cool-pkg"
-    }
-  }
-```
-
-## Trusted dependencies
-
-Unlike other npm clients, Bun does not execute arbitrary lifecycle scripts for installed dependencies, such as `postinstall`. These scripts represent a potential security risk, as they can execute arbitrary code on your machine.
-
-<!-- Bun maintains an allow-list of popular packages containing `postinstall` scripts that are known to be safe. To run lifecycle scripts for packages that aren't on this list, add the package to `trustedDependencies` in your package.json. -->
-
-To tell Bun to allow lifecycle scripts for a particular package, add the package to `trustedDependencies` in your package.json.
-
-<!-- ```json-diff
-  {
-    "name": "my-app",
-    "version": "1.0.0",
-+   "trustedDependencies": {
-+     "my-trusted-package": "*"
-+   }
-  }
-``` -->
-
-```json-diff
-  {
-    "name": "my-app",
-    "version": "1.0.0",
-+   "trustedDependencies": ["my-trusted-package"]
-  }
+$ bun install --dry-run
 ```
 
-Bun reads this field and will run lifecycle scripts for `my-trusted-package`.
-
-<!-- If you specify a version range, Bun will only execute lifecycle scripts if the resolved package version matches the range. -->
-<!--
-```json
-{
-  "name": "my-app",
-  "version": "1.0.0",
-  "trustedDependencies": {
-    "my-trusted-package": "^1.0.0"
-  }
-}
-``` -->
-
-## Git dependencies
+## Non-npm dependencies
 
-To add a dependency from a git repository:
+Bun supports installing dependencies from Git, GitHub, and local or remotely-hosted tarballs. For complete documentation refer to [Package manager > Git, GitHub, and tarball dependencies](/docs/cli/add).
 
-```bash
-$ bun install git@github.com:moment/moment.git
-```
-
-Bun supports a variety of protocols, including [`github`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#github-urls), [`git`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#git-urls-as-dependencies), `git+ssh`, `git+https`, and many more.
-
-```json
+```json#package.json
 {
   "dependencies": {
     "dayjs": "git+https://github.com/iamkun/dayjs.git",
     "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21",
     "moment": "git@github.com:moment/moment.git",
-    "zod": "github:colinhacks/zod"
+    "zod": "github:colinhacks/zod",
+    "react": "https://registry.npmjs.org/react/-/react-18.2.0.tgz"
   }
 }
 ```
 
-## Tarball dependencies
+## Configuration
 
-A package name can correspond to a publicly hosted `.tgz` file. During `bun install`, Bun will download and install the package from the specified tarball URL, rather than from the package registry.
+The default behavior of `bun install` can be configured in `bunfig.toml`. The default values are shown below.
 
-```json#package.json
-{
-  "dependencies": {
-    "zod": "https://registry.npmjs.org/zod/-/zod-3.21.4.tgz"
-  }
-}
+```toml
+[install]
+
+# whether to install optionalDependencies
+optional = true
+
+# whether to install devDependencies
+dev = true
+
+# whether to install peerDependencies
+peer = false
+
+# equivalent to `--production` flag
+production = false
+
+# equivalent to `--frozen-lockfile` flag
+frozenLockfile = false
+
+# equivalent to `--dry-run` flag
+dryRun = false
 ```
 
 ## CI/CD
 
-Looking to speed up your CI? Use the official `oven-sh/setup-bun` action to install `bun` in a GitHub Actions pipeline.
+Looking to speed up your CI? Use the official [`oven-sh/setup-bun`](https://github.com/oven-sh/setup-bun) action to install `bun` in a GitHub Actions pipeline.
 
 ```yaml#.github/workflows/release.yml
 name: bun-types
diff --git a/docs/cli/link.md b/docs/cli/link.md
new file mode 100644
index 000000000..9adc73765
--- /dev/null
+++ b/docs/cli/link.md
@@ -0,0 +1,46 @@
+Use `bun link` in a local directory to register the current package as a "linkable" package.
+
+```bash
+$ cd /path/to/cool-pkg
+$ cat package.json
+{
+  "name": "cool-pkg",
+  "version": "1.0.0"
+}
+$ bun link
+bun link v1.x (7416672e)
+Success! Registered "cool-pkg"
+
+To use cool-pkg in a project, run:
+  bun link cool-pkg
+
+Or add it in dependencies in your package.json file:
+  "cool-pkg": "link:cool-pkg"
+```
+
+This package can now be "linked" into other projects using `bun link cool-pkg`. This will create a symlink in the `node_modules` directory of the target project, pointing to the local directory.
+
+```bash
+$ cd /path/to/my-app
+$ bun link cool-pkg
+```
+
+In addition, the `--save` flag can be used to add `cool-pkg` to the `dependencies` field of your app's package.json with a special version specifier that tells Bun to load from the registered local directory instead of installing from `npm`:
+
+```json-diff
+  {
+    "name": "my-app",
+    "version": "1.0.0",
+    "dependencies": {
++     "cool-pkg": "link:cool-pkg"
+    }
+  }
+```
+
+To _unregister_ a local package, navigate to the package's root directory and run `bun unlink`.
+
+```bash
+$ cd /path/to/cool-pkg
+$ bun unlink
+bun unlink v1.x (7416672e)
+```
diff --git a/docs/cli/pm.md b/docs/cli/pm.md
new file mode 100644
index 000000000..689f177d8
--- /dev/null
+++ b/docs/cli/pm.md
@@ -0,0 +1,58 @@
+The `bun pm` command group provides a set of utilities for working with Bun's package manager.
+
+To print the path to the `bin` directory for the local project:
+
+```bash
+$ bun pm bin
+/path/to/current/project/node_modules/.bin
+```
+
+To print the path to the global `bin` directory:
+
+```bash
+$ bun pm bin -g
+<$HOME>/.bun/bin
+```
+
+To print a list of installed dependencies in the current project and their resolved versions, excluding their dependencies.
+
+```bash
+$ bun pm ls
+/path/to/project node_modules (135)
+├── eslint@8.38.0
+├── react@18.2.0
+├── react-dom@18.2.0
+├── typescript@5.0.4
+└── zod@3.21.4
+```
+
+To print all installed dependencies, including nth-order dependencies.
+
+```bash
+$ bun pm ls --all
+/path/to/project node_modules (135)
+├── @eslint-community/eslint-utils@4.4.0
+├── @eslint-community/regexpp@4.5.0
+├── @eslint/eslintrc@2.0.2
+├── @eslint/js@8.38.0
+├── @nodelib/fs.scandir@2.1.5
+├── @nodelib/fs.stat@2.0.5
+├── @nodelib/fs.walk@1.2.8
+├── acorn@8.8.2
+├── acorn-jsx@5.3.2
+├── ajv@6.12.6
+├── ansi-regex@5.0.1
+├── ...
+```
+
+To print the path to Bun's global module cache:
+
+```bash
+$ bun pm cache
+```
+
+To clear Bun's global module cache:
+
+```bash
+$ bun pm cache rm
+```
diff --git a/docs/cli/remove.md b/docs/cli/remove.md
new file mode 100644
index 000000000..8054711d3
--- /dev/null
+++ b/docs/cli/remove.md
@@ -0,0 +1,5 @@
+To remove a dependency:
+
+```bash
+$ bun remove ts-node
+```
diff --git a/docs/cli/update.md b/docs/cli/update.md
new file mode 100644
index 000000000..dfda37f01
--- /dev/null
+++ b/docs/cli/update.md
@@ -0,0 +1,7 @@
+To update all dependencies to the latest version _that's compatible with the version range specified in your `package.json`_:
+
+```sh
+$ bun update
+```
+
+This will not edit your `package.json`. There's currently no command to force-update all dependencies to the latest version regardless version ranges.