commands: improve name and key helptexts

License: MIT
Signed-off-by: Lars Gierth <larsg@systemli.org>

core/commands/ipns.go

@@ -13,21 +13,24 @@ import (
 
 var IpnsCmd = &cmds.Command{
 	Helptext: cmds.HelpText{
-		Tagline: "Get the value currently published at an IPNS name.",
+		Tagline: "Resolve IPNS names.",
 		ShortDescription: `
 IPNS is a PKI namespace, where names are the hashes of public keys, and
-the private key enables publishing new (signed) values. In resolve, the
-default value of <name> is your own identity public key.
+the private key enables publishing new (signed) values. In both publish
+and resolve, the default name used is the node's own PeerID,
+which is the hash of its public key.
 `,
 		LongDescription: `
 IPNS is a PKI namespace, where names are the hashes of public keys, and
-the private key enables publishing new (signed) values. In resolve, the
-default value of <name> is your own identity public key.
+the private key enables publishing new (signed) values. In both publish
+and resolve, the default name used is the node's own PeerID,
+which is the hash of its public key.
 
+You can use the 'ipfs key' commands to list and generate more names and their respective keys.
 
 Examples:
 
-Resolve the value of your identity:
+Resolve the value of your name:
 
   > ipfs name resolve
   /ipfs/QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
@@ -37,7 +40,7 @@ Resolve the value of another name:
   > ipfs name resolve QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ
   /ipfs/QmSiTko9JZyabH56y2fussEt1A5oDqsFXB3CkvAqraFryz
 
-Resolve the value of a reference:
+Resolve the value of a dnslink:
 
   > ipfs name resolve ipfs.io
   /ipfs/QmaBvfZooxWkrv7D3r8LS9moNjzD2o525XMZze69hhoxf5
@@ -91,7 +94,7 @@ Resolve the value of a reference:
 		var name string
 		if len(req.Arguments()) == 0 {
 			if n.Identity == "" {
-				res.SetError(errors.New("Identity not loaded!"), cmds.ErrNormal)
+				res.SetError(errors.New("identity not loaded"), cmds.ErrNormal)
 				return
 			}
 			name = n.Identity.Pretty()

core/commands/keystore.go

@@ -18,7 +18,19 @@ import (
 
 var KeyCmd = &cmds.Command{
 	Helptext: cmds.HelpText{
-		Tagline: "Create and manipulate keypairs",
+		Tagline: "Create and list IPNS name keypairs",
+		ShortDescription: `
+'ipfs key gen' generates a new keypair for usage with IPNS and 'ipfs name publish'.
+
+  > ipfs key gen --type=rsa --size=2048 mykey
+  > ipfs name publish --key=mykey QmSomeHash
+
+'ipfs key list' lists the available keys.
+
+  > ipfs key list
+  self
+  mykey
+		`,
 	},
 	Subcommands: map[string]*cmds.Command{
 		"gen":  KeyGenCmd,

core/commands/name.go

@@ -9,31 +9,35 @@ type IpnsEntry struct {
 
 var NameCmd = &cmds.Command{
 	Helptext: cmds.HelpText{
-		Tagline: "Interact with the IPFS namespace (IPNS).",
+		Tagline: "Publish and resolve IPNS names.",
 		ShortDescription: `
 IPNS is a PKI namespace, where names are the hashes of public keys, and
 the private key enables publishing new (signed) values. In both publish
-and resolve, the default value of <name> is your own identity public key.
+and resolve, the default name used is the node's own PeerID,
+which is the hash of its public key.
 `,
 		LongDescription: `
 IPNS is a PKI namespace, where names are the hashes of public keys, and
 the private key enables publishing new (signed) values. In both publish
-and resolve, the default value of <name> is your own identity public key.
+and resolve, the default name used is the node's own PeerID,
+which is the hash of its public key.
 
+You can use the 'ipfs key' commands to list and generate more names and their respective keys.
 
 Examples:
 
-Publish an <ipfs-path> to your identity name:
+Publish an <ipfs-path> with your default name:
 
   > ipfs name publish /ipfs/QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
   Published to QmbCMUZw6JFeZ7Wp9jkzbye3Fzp2GGcPgC3nmeUjfVF87n: /ipfs/QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
 
-Publish an <ipfs-path> to another public key:
+Publish an <ipfs-path> with another name, added by an 'ipfs key' command:
 
-  > ipfs name publish /ipfs/QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy QmbCMUZw6JFeZ7Wp9jkzbye3Fzp2GGcPgC3nmeUjfVF87n
+  > ipfs key gen --type=rsa --size=2048 mykey
+  > ipfs name publish --key=mykey /ipfs/QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
   Published to QmbCMUZw6JFeZ7Wp9jkzbye3Fzp2GGcPgC3nmeUjfVF87n: /ipfs/QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
 
-Resolve the value of your identity:
+Resolve the value of your name:
 
   > ipfs name resolve
   /ipfs/QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
@@ -43,7 +47,7 @@ Resolve the value of another name:
   > ipfs name resolve QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ
   /ipfs/QmSiTko9JZyabH56y2fussEt1A5oDqsFXB3CkvAqraFryz
 
-Resolve the value of a reference:
+Resolve the value of a dnslink:
 
   > ipfs name resolve ipfs.io
   /ipfs/QmaBvfZooxWkrv7D3r8LS9moNjzD2o525XMZze69hhoxf5

core/commands/publish.go

@@ -20,27 +20,32 @@ var errNotOnline = errors.New("This command must be run in online mode. Try runn
 
 var PublishCmd = &cmds.Command{
 	Helptext: cmds.HelpText{
-		Tagline: "Publish an object to IPNS.",
+		Tagline: "Publish IPNS names.",
 		ShortDescription: `
 IPNS is a PKI namespace, where names are the hashes of public keys, and
-the private key enables publishing new (signed) values. In publish, the
-default value of <name> is your own identity public key.
+the private key enables publishing new (signed) values. In both publish
+and resolve, the default name used is the node's own PeerID,
+which is the hash of its public key.
 `,
 		LongDescription: `
 IPNS is a PKI namespace, where names are the hashes of public keys, and
-the private key enables publishing new (signed) values. In publish, the
-default value of <name> is your own identity public key.
+the private key enables publishing new (signed) values. In both publish
+and resolve, the default name used is the node's own PeerID,
+which is the hash of its public key.
+
+You can use the 'ipfs key' commands to list and generate more names and their respective keys.
 
 Examples:
 
-Publish an <ipfs-path> to your identity name:
+Publish an <ipfs-path> with your default name:
 
   > ipfs name publish /ipfs/QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
   Published to QmbCMUZw6JFeZ7Wp9jkzbye3Fzp2GGcPgC3nmeUjfVF87n: /ipfs/QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
 
-Publish an <ipfs-path> to another public key (not implemented):
+Publish an <ipfs-path> with another name, added by an 'ipfs key' command:
 
-  > ipfs name publish /ipfs/QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy QmbCMUZw6JFeZ7Wp9jkzbye3Fzp2GGcPgC3nmeUjfVF87n
+  > ipfs key gen --type=rsa --size=2048 mykey
+  > ipfs name publish --key=mykey /ipfs/QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
   Published to QmbCMUZw6JFeZ7Wp9jkzbye3Fzp2GGcPgC3nmeUjfVF87n: /ipfs/QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
 
 `,
@@ -56,7 +61,7 @@ Publish an <ipfs-path> to another public key (not implemented):
     This accepts durations such as "300s", "1.5h" or "2h45m". Valid time units are
     "ns", "us" (or "µs"), "ms", "s", "m", "h".`).Default("24h"),
 		cmds.StringOption("ttl", "Time duration this record should be cached for (caution: experimental)."),
-		cmds.StringOption("key", "k", "name of key to use").Default("self"),
+		cmds.StringOption("key", "k", "Name of the key to be used, as listed by 'ipfs key list'. Default: <<default>>.").Default("self"),
 	},
 	Run: func(req cmds.Request, res cmds.Response) {
 		log.Debug("begin publish")
@@ -75,14 +80,14 @@ Publish an <ipfs-path> to another public key (not implemented):
 		}
 
 		if n.Mounts.Ipns != nil && n.Mounts.Ipns.IsActive() {
-			res.SetError(errors.New("You cannot manually publish while IPNS is mounted."), cmds.ErrNormal)
+			res.SetError(errors.New("cannot manually publish while IPNS is mounted"), cmds.ErrNormal)
 			return
 		}
 
 		pstr := req.Arguments()[0]
 
 		if n.Identity == "" {
-			res.SetError(errors.New("Identity not loaded!"), cmds.ErrNormal)
+			res.SetError(errors.New("identity not loaded"), cmds.ErrNormal)
 			return
 		}
 

core/commands/root.go

@@ -41,12 +41,12 @@ ADVANCED COMMANDS
   daemon        Start a long-running daemon process
   mount         Mount an IPFS read-only mountpoint
   resolve       Resolve any type of name
-  name          Publish or resolve IPNS names
+  name          Publish and resolve IPNS names
+  key           Create and list IPNS name keypairs
   dns           Resolve DNS links
   pin           Pin objects to local storage
   repo          Manipulate the IPFS repository
   stats         Various operational stats
-  key           Create and manipulate keypairs
 
 NETWORK COMMANDS
   id            Show info about IPFS peers