diff --git a/core/commands/files/files.go b/core/commands/files/files.go
index ce6c6522ebb..e973c2ba69e 100644
--- a/core/commands/files/files.go
+++ b/core/commands/files/files.go
@@ -284,9 +284,9 @@ type FilesLsOutput struct {
 
 var FilesLsCmd = &cmds.Command{
 	Helptext: cmds.HelpText{
-		Tagline: "List directories.",
+		Tagline: "List directories in the local mutable namespace.",
 		ShortDescription: `
-List directories.
+List directories in the local mutable namespace.
 
 Examples:
 
diff --git a/core/commands/ls.go b/core/commands/ls.go
index 7cbefc10c7d..b0de779ef0e 100644
--- a/core/commands/ls.go
+++ b/core/commands/ls.go
@@ -32,12 +32,14 @@ type LsOutput struct {
 
 var LsCmd = &cmds.Command{
 	Helptext: cmds.HelpText{
-		Tagline: "List links from an object.",
+		Tagline: "List directory contents for Unix filesystem objects.",
 		ShortDescription: `
-Displays the links an IPFS or IPNS object(s) contains, with the following
-format:
+Displays the contents of an IPFS or IPNS object(s) at the given path, with
+the following format:
 
   <link base58 hash> <link size in bytes> <link name>
+
+The JSON output contains type information.
 `,
 	},
 
diff --git a/core/commands/unixfs/ls.go b/core/commands/unixfs/ls.go
index 108d115c6b3..757ee154b44 100644
--- a/core/commands/unixfs/ls.go
+++ b/core/commands/unixfs/ls.go
@@ -42,6 +42,9 @@ Displays the contents of an IPFS or IPNS object(s) at the given path.
 The JSON output contains size information. For files, the child size
 is the total size of the file contents. For directories, the child
 size is the IPFS link size.
+
+This functionality is deprecated, and will be removed in future versions. If
+possible, please use 'ipfs ls' instead.
 `,
 		LongDescription: `
 Displays the contents of an IPFS or IPNS object(s) at the given path.
@@ -59,6 +62,9 @@ Example:
     cat.jpg
     > ipfs file ls /ipfs/QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ
     cat.jpg
+
+This functionality is deprecated, and will be removed in future versions. If
+possible, please use 'ipfs ls' instead.
 `,
 	},