diff --git a/README.md b/README.md
index b60cd08d..e5aee277 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ This package implements the following commands:
 
 ### wp media
 
-Imports files as attachments, regenerates thumbnails, or lists registered image sizes.
+Imports files as attachments, regenerates thumbnails, replaces existing attachment files, or lists registered image sizes.
 
 ~~~
 wp media
@@ -336,6 +336,46 @@ wp media regenerate [<attachment-id>...] [--image_size=<image_size>...] [--skip-
 
 
 
+### wp media replace
+
+Replaces the file for an existing attachment while preserving its identity.
+
+~~~
+wp media replace <attachment-id> <file> [--skip-delete] [--porcelain]
+~~~
+
+**OPTIONS**
+
+	<attachment-id>
+		ID of the attachment whose file is to be replaced.
+
+	<file>
+		Path to the replacement file. Supports local paths and URLs.
+
+	[--skip-delete]
+		Skip deletion of old thumbnail files after replacement.
+
+	[--porcelain]
+		Output just the attachment ID after replacement.
+
+**EXAMPLES**
+
+    # Replace an attachment file with a local file.
+    $ wp media replace 123 ~/new-image.jpg
+    Replaced file for attachment ID 123 with '/home/user/new-image.jpg'.
+    Success: Replaced 1 of 1 images.
+
+    # Replace an attachment file with a file from a URL.
+    $ wp media replace 123 'http://example.com/image.jpg'
+    Replaced file for attachment ID 123 with 'http://example.com/image.jpg'.
+    Success: Replaced 1 of 1 images.
+
+    # Replace and output just the attachment ID.
+    $ wp media replace 123 ~/new-image.jpg --porcelain
+    123
+
+
+
 ### wp media image-size
 
 Lists image sizes registered with WordPress.