docs: CLI docs for pin remote commands
This adds docs in form of longer description that is displayed when --help is passes on the CLI. While at it, unified some language to match fields in the config file and other places + included some tips and best practices which should improve onboarding experience.
Marcin Rataj committed
Dec 11, 2020 at 14:43 UTC
3b82dd8e55e5e984c44a182d1aaa42d86e61d298
1 file changed
+92
-20
core/commands/pin/remotepin.go
+92
-20
@@ -56,7 +56,7 @@ const pinNameOptionName = "name"
56
const pinCIDsOptionName = "cid"
57
const pinStatusOptionName = "status"
58
const pinServiceNameOptionName = "service"
59
-const pinServiceURLOptionName = "url"
59
+const pinServiceEndpointOptionName = "endpoint"
60
const pinServiceKeyOptionName = "key"
61
const pinServiceStatOptionName = "stat"
62
const pinBackgroundOptionName = "background"
@@ -89,20 +89,41 @@ func printRemotePinDetails(w io.Writer, out *RemotePinOutput) {
89
90
// remote pin commands
91
92
-var pinServiceNameOption = cmds.StringOption(pinServiceNameOptionName, "Name of the remote pinning service to use.")
92
+var pinServiceNameOption = cmds.StringOption(pinServiceNameOptionName, "Name of the remote pinning service to use (mandatory).")
93
94
var addRemotePinCmd = &cmds.Command{
95
Helptext: cmds.HelpText{
96
Tagline: "Pin object to remote pinning service.",
97
- ShortDescription: "Stores an IPFS object from a given path to a remote pinning service.",
97
+ ShortDescription: "Asks remote pinning service to pin an IPFS object from a given path.",
98
+ LongDescription: `
99
+Asks remote pinning service to pin an IPFS object from a given path or a CID.
100
+
101
+To pin CID 'bafkqaaa' to service named 'mysrv' under a pin named 'mypin':
102
+
103
+ $ ipfs pin remote add --service=mysrv --name=mypin bafkqaaa
104
+
105
+The above command will block until remote service returns 'pinned' status,
106
+which may take time depending on the size and available providers of the pinned
107
+data.
108
+
109
+If you prefer to not wait for pinning confirmation and return immediatelly
110
+after remote service confirms 'queued' status, add the '--background' flag:
111
+
112
+ $ ipfs pin remote add --service=mysrv --name=mypin --background bafkqaaa
113
+
114
+Status of background pin requests can be inspected with the 'ls' command:
115
+
116
+ $ ipfs pin remote ls --service=mysrv --cid=bafkqaaa --status=queued,pinning,pinned,failed
117
+
118
+`,
119
},
120
121
Arguments: []cmds.Argument{
101
- cmds.StringArg("ipfs-path", true, false, "Path to object(s) to be pinned."),
122
+ cmds.StringArg("ipfs-path-or-cid", true, false, "Path to object(s) to be pinned."),
123
},
124
Options: []cmds.Option{
104
- cmds.StringOption(pinNameOptionName, "An optional name for the pin."),
125
pinServiceNameOption,
126
+ cmds.StringOption(pinNameOptionName, "An optional name for the pin."),
127
cmds.BoolOption(pinBackgroundOptionName, "Add to the queue on the remote service and return immediately (does not wait for pinned status).").WithDefault(false),
128
},
129
Type: RemotePinOutput{},
@@ -218,15 +239,18 @@ Returns a list of objects that are pinned to a remote pinning service.
239
`,
240
LongDescription: `
241
Returns a list of objects that are pinned to a remote pinning service.
242
+
243
+NOTE: by default it will only show matching objects in 'pinned' state.
244
+Pass '--status=queued,pinning,pinned,failed' to list pins in all states.
245
`,
246
},
247
248
Arguments: []cmds.Argument{},
249
Options: []cmds.Option{
226
- cmds.StringOption(pinNameOptionName, "Return pins objects with names that contain provided value (case-sensitive, exact match)."),
227
- cmds.DelimitedStringsOption(",", pinCIDsOptionName, "Return only pin objects for the specified CID(s); optional, comma separated."),
228
- cmds.DelimitedStringsOption(",", pinStatusOptionName, "Return only pin objects with the specified statuses (queued,pinning,pinned,failed)").WithDefault([]string{"pinned"}),
250
pinServiceNameOption,
251
+ cmds.StringOption(pinNameOptionName, "Return pins with names that contain provided value (case-sensitive, exact match)."),
252
+ cmds.DelimitedStringsOption(",", pinCIDsOptionName, "Return pins for the specified CIDs (comma separated)."),
253
+ cmds.DelimitedStringsOption(",", pinStatusOptionName, "Return pins with the specified statuses (queued,pinning,pinned,failed).").WithDefault([]string{"pinned"}),
254
},
255
Run: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error {
256
ctx, cancel := context.WithCancel(req.Context)
@@ -300,20 +324,41 @@ func lsRemote(ctx context.Context, req *cmds.Request, c *pinclient.Client) (chan
324
325
var rmRemotePinCmd = &cmds.Command{
326
Helptext: cmds.HelpText{
303
- Tagline: "Remove pinned objects from remote pinning service.",
304
- ShortDescription: `
305
-Removes the pin from the given object allowing it to be garbage
306
-collected if needed.
327
+ Tagline: "Remove pins from remote pinning service.",
328
+ ShortDescription: "Removes the remote pin allowing it to be garbage collected if needed.",
329
+ LongDescription: `
330
+Removes remote pins allowing them to be garbage collected if needed.
331
+
332
+This command accepts the same search query parameters as 'ls' and it is a good
333
+practice to execute 'ls' before 'rm' to confirm the list of pins to be removed.
334
+
335
+To remove a single pin for a specific CID:
336
+
337
+ $ ipfs pin remote ls --service=mysrv --cid=bafkqaaa
338
+ $ ipfs pin remote rm --service=mysrv --cid=bafkqaaa
339
+
340
+When more than one pin is matching the query on the remote service an error is
341
+returned. To confirm removal of multiple pins pass '--force':
342
+
343
+ $ ipfs pin remote ls --service=mysrv --name=popular-name
344
+ $ ipfs pin remote rm --service=mysrv --name=popular-name --force
345
+
346
+NOTE: When no '--status' is passed, implicit '--status=pinned' is used.
347
+To list and then remove all pending pin requests pass an explicit status list:
348
+
349
+ $ ipfs pin remote ls --service=mysrv --status=queued,pinning,failed
350
+ $ ipfs pin remote rm --service=mysrv --status=queued,pinning,failed --force
351
+
352
`,
353
},
354
355
Arguments: []cmds.Argument{},
356
Options: []cmds.Option{
357
pinServiceNameOption,
313
- cmds.StringOption(pinNameOptionName, "Remove pin objects with names that contain provided value (case-sensitive, exact match)."),
314
- cmds.DelimitedStringsOption(",", pinCIDsOptionName, "Remove only pin objects for the specified CID(s)."),
315
- cmds.DelimitedStringsOption(",", pinStatusOptionName, "Remove only pin objects with the specified statuses (queued,pinning,pinned,failed).").WithDefault([]string{"pinned"}),
316
- cmds.BoolOption(pinForceOptionName, "Remove multiple pins without confirmation.").WithDefault(false),
358
+ cmds.StringOption(pinNameOptionName, "Remove pins with names that contain provided value (case-sensitive, exact match)."),
359
+ cmds.DelimitedStringsOption(",", pinCIDsOptionName, "Remove pins for the specified CIDs."),
360
+ cmds.DelimitedStringsOption(",", pinStatusOptionName, "Remove pins with the specified statuses (queued,pinning,pinned,failed).").WithDefault([]string{"pinned"}),
361
+ cmds.BoolOption(pinForceOptionName, "Allow removal of multiple pins matching the query without additional confirmation.").WithDefault(false),
362
},
363
Run: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error {
364
ctx, cancel := context.WithCancel(req.Context)
@@ -359,10 +404,25 @@ var addRemotePinServiceCmd = &cmds.Command{
404
Helptext: cmds.HelpText{
405
Tagline: "Add remote pinning service.",
406
ShortDescription: "Add a credentials for access to a remote pinning service.",
407
+ LongDescription: `
408
+Add a credentials for access to a remote pinning service and store them in the
409
+config under Pinning.RemoteServices map.
410
+
411
+TIP:
412
+
413
+ To add services and test them by fetching pin count stats:
414
+
415
+ $ ipfs pin remote service add goodsrv https://pin-api.example.com secret-key
416
+ $ ipfs pin remote service add badsrv https://bad-api.example.com invalid-key
417
+ $ ipfs pin remote service ls --stat
418
+ goodsrv https://pin-api.example.com 0/0/0/0
419
+ badsrv https://bad-api.example.com invalid
420
+
421
+`,
422
},
423
Arguments: []cmds.Argument{
424
cmds.StringArg(pinServiceNameOptionName, true, false, "Service name."),
365
- cmds.StringArg(pinServiceURLOptionName, true, false, "Service URL."),
425
+ cmds.StringArg(pinServiceEndpointOptionName, true, false, "Service endpoint."),
426
cmds.StringArg(pinServiceKeyOptionName, true, false, "Service key."),
427
},
428
Type: nil,
@@ -378,7 +438,7 @@ var addRemotePinServiceCmd = &cmds.Command{
438
defer repo.Close()
439
440
if len(req.Arguments) < 3 {
381
- return fmt.Errorf("expecting three arguments: service name, url and key")
441
+ return fmt.Errorf("expecting three arguments: service name, endpoint and key")
442
}
443
444
name := req.Arguments[0]
@@ -387,7 +447,7 @@ var addRemotePinServiceCmd = &cmds.Command{
447
448
u, err := neturl.ParseRequestURI(url)
449
if err != nil || !strings.HasPrefix(u.Scheme, "http") {
390
- return fmt.Errorf("service url must be a valid HTTP URL")
450
+ return fmt.Errorf("service endpoint must be a valid HTTP URL")
451
}
452
453
cfg, err := repo.Config()
@@ -419,7 +479,7 @@ var rmRemotePinServiceCmd = &cmds.Command{
479
ShortDescription: "Remove credentials for access to a remote pinning service.",
480
},
481
Arguments: []cmds.Argument{
422
- cmds.StringArg("remote-pin-service", true, false, "Name of remote pinning service to remove."),
482
+ cmds.StringArg(pinServiceNameOptionName, true, false, "Name of remote pinning service to remove."),
483
},
484
Options: []cmds.Option{},
485
Type: nil,
@@ -454,6 +514,18 @@ var lsRemotePinServiceCmd = &cmds.Command{
514
Helptext: cmds.HelpText{
515
Tagline: "List remote pinning services.",
516
ShortDescription: "List remote pinning services.",
517
+ LongDescription: `
518
+List remote pinning services.
519
+
520
+By default only a name and an endpoint are listed, however one can pass '--stat'
521
+to test each endpoint by fetching pin counts for each state:
522
+
523
+ $ ipfs pin remote service ls --stat
524
+ goodsrv https://pin-api.example.com 0/0/0/0
525
+ badsrv https://bad-api.example.com invalid
526
+
527
+TIP: pass '--enc=json' for more useful JSON output.
528
+`,
529
},
530
Arguments: []cmds.Argument{},
531
Options: []cmds.Option{