diff --git a/core/commands/files/files.go b/core/commands/files/files.go
index 750cddaa94e..a9b97f1a964 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.
 `,
 	},