1 files changed, 46 insertions, 0 deletions
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)
+```