docs: improve CLI command descriptions for autogenned docs

pkg/cli/auth.go

@@ -160,11 +160,11 @@ func newAuthCommand() *cli.Command {
 		Description: `Authenticate with the Pinner.xyz service.
 
 Ways to authenticate:
-  1. Provide JWT token directly: pinner auth <jwt-token>
+  1. Provide an auth token directly: pinner auth <token>
   2. Interactive login: pinner auth (prompts for all inputs)
   3. Semi-interactive: pinner auth --email user@example.com (prompts for password and OTP if needed)
-  4. Non-interactive: PINNER_EMAIL=x PINNER_PASSWORD=y pinner auth
-  5. Non-interactive with 2FA: PINNER_EMAIL=x PINNER_PASSWORD=y PINNER_OTP=123456 pinner auth
+  4. Non-interactive: PINNER_EMAIL=x PINNER_PASSWORD=*** pinner auth
+  5. Non-interactive with 2FA: PINNER_EMAIL=x PINNER_PASSWORD=*** PINNER_OTP=123456 pinner auth
   6. Secure non-interactive: echo "pass" | pinner auth --email user@example.com
 
 Examples:
@@ -173,7 +173,7 @@ Examples:
   pinner auth --email user@example.com --password mypass --otp-code 123456
   PINNER_EMAIL=user@example.com PINNER_PASSWORD=mypass pinner auth
   echo "mypass" | pinner auth --email user@example.com --key-name "my-laptop"`,
-		ArgsUsage: "[jwt-token]",
+		ArgsUsage: "[token]",
 		Flags: []cli.Flag{
 			&cli.StringFlag{
 				Name:    FlagEmail,
@@ -204,7 +204,7 @@ Examples:
 			},
 			&cli.BoolFlag{
 				Name:  FlagNoCreateKey,
-				Usage: "Skip API key creation, save JWT directly",
+				Usage: "Skip API key creation, save token directly",
 			},
 			&cli.BoolFlag{
 				Name:  FlagForce,

pkg/cli/dns.go

@@ -113,7 +113,7 @@ func newDNSZonesGetCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "get",
 		Usage: "Get a DNS zone by domain",
-		Description: `Get details of a specific DNS zone by domain name or ID.
+		Description: `Get details of a specific DNS zone.
 
 Examples:
   pinner dns zones get example.com
@@ -129,7 +129,7 @@ func newDNSZonesDeleteCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "delete",
 		Usage: "Delete a DNS zone",
-		Description: `Delete a DNS zone and all its records by domain name or ID.
+		Description: `Delete a DNS zone and all its records.
 
 Examples:
   pinner dns zones delete example.com`,
@@ -185,7 +185,7 @@ func newDNSRecordsListCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "list",
 		Usage: "List DNS records for a zone",
-		Description: `List all DNS records for a specific zone by domain name or ID.
+		Description: `List all DNS records for a specific zone.
 
 Examples:
   pinner dns records list example.com
@@ -201,11 +201,11 @@ func newDNSRecordsCreateCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "create",
 		Usage: "Create a DNS record",
-		Description: `Create a new DNS record in a zone.
+		Description: `Create a DNS record in the specified zone.
 
 Examples:
   pinner dns records create example.com --name www --type CNAME --content example.com
-  pinner dns records create example.com --name _dnslink --type TXT --content "/ipfs/QmHash" --ttl 3600
+  pinner dns records create example.com --name _dnslink --type TXT --content "/ipfs/bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e" --ttl 3600
   pinner dns records create example.com --name @ --type A --content 192.168.1.1 --json`,
 		ArgsUsage: "<domain>",
 		Flags: []cli.Flag{

pkg/cli/download.go

@@ -35,12 +35,12 @@ For streaming content to stdout, use 'pinner cat' instead.
 For listing directory contents, use 'pinner ls' instead.
 
 Examples:
-  pinner download QmHash
-  pinner download QmHash/subdir/file.txt
-  pinner download QmHash -o myfile.txt
-  pinner download QmHash -o /path/to/dir/
-  pinner download QmHash -o existing.txt --force
-  pinner download QmHash --dry-run
+  pinner download bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e
+  pinner download bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e/subdir/file.txt
+  pinner download bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e -o myfile.txt
+  pinner download bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e -o /path/to/dir/
+  pinner download bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e -o existing.txt --force
+  pinner download bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --dry-run
 
 The output includes:
   - CID: Content identifier of the downloaded file
@@ -76,11 +76,11 @@ func newCatCommand() *cli.Command {
 Supports CID paths (e.g., CID/path/to/file) to cat a specific file from a directory.
 
 Examples:
-  pinner cat QmHash
-  pinner cat QmHash/path/to/file.txt
-  pinner cat QmHash > output.txt
-  pinner cat QmHash | jq .
-  pinner cat QmHash | gzip > data.gz
+  pinner cat bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e
+  pinner cat bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e/path/to/file.txt
+  pinner cat bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e > output.txt
+  pinner cat bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e | jq .
+  pinner cat bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e | gzip > data.gz
 
 Note: This command outputs raw content to stdout.
 Use --verbose or redirect stderr for progress info.`,
@@ -111,10 +111,10 @@ Supports CID paths (e.g., CID/path/to/dir) to list nested directories.
 If the path targets a file, shows file metadata instead of erroring.
 
 Examples:
-  pinner ls QmHash
-  pinner ls QmHash --json
-  pinner ls QmHash --limit 5
-  pinner ls QmHash/subdir`,
+  pinner ls bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e
+  pinner ls bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --json
+  pinner ls bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --limit 5
+  pinner ls bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e/subdir`,
 		ArgsUsage: "<cid>[/<path>]",
 		Flags: []cli.Flag{
 			LimitFlag(),

pkg/cli/flags.go

@@ -406,7 +406,7 @@ func RequiredDomainFlag() *cli.StringFlag {
 func TargetHashFlag() *cli.StringFlag {
 	return &cli.StringFlag{
 		Name:  FlagTargetHash,
-		Usage: "Target CID (IPFS hash) for the website",
+		Usage: "Target CID for the website",
 	}
 }
 
@@ -415,7 +415,7 @@ func TargetHashFlag() *cli.StringFlag {
 func RequiredTargetHashFlag() *cli.StringFlag {
 	return &cli.StringFlag{
 		Name:     FlagTargetHash,
-		Usage:    "Target CID (IPFS hash) for the website",
+		Usage:    "Target CID for the website",
 		Required: true,
 	}
 }
@@ -424,15 +424,15 @@ func RequiredTargetHashFlag() *cli.StringFlag {
 func CIDFlag() *cli.StringFlag {
 	return &cli.StringFlag{
 		Name:  FlagCID,
-		Usage: "CID (Content Identifier) for the website",
+		Usage: "CID for the website",
 	}
 }
 
 // RequiredCIDFlag returns a required flag for the target CID.
 func RequiredCIDFlag() *cli.StringFlag {
 	return &cli.StringFlag{
 		Name:     FlagCID,
-		Usage:    "CID (Content Identifier) for the website",
+		Usage:    "CID for the website",
 		Required: true,
 	}
 }

pkg/cli/flags_test.go

@@ -162,7 +162,7 @@ func TestCommandArgsVerification(t *testing.T) {
 		{
 			name:        "auth command",
 			commandName: "auth",
-			argsUsage:   "[jwt-token]",
+			argsUsage:   "[token]",
 			minArgs:     0,
 			maxArgs:     1,
 		},

pkg/cli/ipns.go

@@ -15,15 +15,15 @@ func newIPNSCommand() *cli.Command {
 		Category: "Management",
 		Usage:    "Manage IPNS (InterPlanetary Name System) keys and records",
 		Description: `IPNS provides a mutable address scheme for IPFS content, allowing you to
-publish content under a stable name that can be updated to point to new CIDs.
+publish content under a stable name that you can update to point to new CIDs.
 
 IPNS operations include:
   - Managing IPNS keys (create, list, get, delete)
   - Publishing CIDs to IPNS names
   - Republishing IPNS records
   - Resolving IPNS names to their target CIDs
 
-Key names can be used interchangeably with numeric IDs. For example:
+Key names and numeric IDs are interchangeable. For example:
   pinner ipns keys get my-key
 is equivalent to:
   pinner ipns keys get 1
@@ -33,7 +33,7 @@ Examples:
   pinner ipns keys create my-key
   pinner ipns keys get my-key
   pinner ipns keys delete my-key
-  pinner ipns publish QmHash --key-name my-key
+  pinner ipns publish bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --key-name my-key
   pinner ipns republish my-key
   pinner ipns resolve k51qzi5uqu5djx...`,
 		Commands: []*cli.Command{
@@ -50,9 +50,9 @@ func newIPNSKeysCommand() *cli.Command {
 		Name:  "keys",
 		Usage: "Manage IPNS keys",
 		Description: `Manage your IPNS keys. Keys are used to publish content under stable
-IPNS names that can be updated to point to new CIDs.
+IPNS names that you can update to point to new CIDs.
 
-Key names can be used interchangeably with numeric IDs.
+Key names and numeric IDs are interchangeable.
 
 Examples:
   pinner ipns keys list
@@ -87,7 +87,7 @@ func newIPNSKeysCreateCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "create",
 		Usage: "Create a new IPNS key",
-		Description: `Create a new IPNS key with the given name. The key can be used to
+		Description: `Create a new IPNS key with the given name. Use the key to
 publish content under a stable IPNS name.
 
 Examples:
@@ -147,12 +147,12 @@ func newIPNSPublishCommand() *cli.Command {
 		Description: `Publish a CID to an IPNS key, making it resolvable via the IPNS name.
 After publishing, the IPNS name will resolve to the specified CID.
 
-The key can be specified by name or numeric ID.
+Specify the key by name or numeric ID.
 
 Examples:
-  pinner ipns publish QmHash --key-name my-key
-  pinner ipns publish QmHash --key-name my-key --ttl 24h
-  pinner ipns publish QmHash --key-name 1 --json`,
+  pinner ipns publish bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --key-name my-key
+  pinner ipns publish bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --key-name my-key --ttl 24h
+  pinner ipns publish bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --key-name 1 --json`,
 		ArgsUsage: "<cid>",
 		Flags: []cli.Flag{
 			&cli.StringFlag{
@@ -181,7 +181,7 @@ func newIPNSRepublishCommand() *cli.Command {
 		Description: `Republish the IPNS record for a specific key. This refreshes the record
 on the network, extending its validity.
 
-The key can be specified by name or numeric ID.
+Specify the key by name or numeric ID.
 
 Examples:
   pinner ipns republish my-key

pkg/cli/list.go

@@ -14,7 +14,7 @@ func newListCommand() *cli.Command {
 		Name:     "list",
 		Category: "Pinning",
 		Usage:    "List pinned content (see: pinner pins ls)",
-		Description: `List your pinned content with optional filtering.
+		Description: `Shortcut for 'pinner pins ls'. List your pinned content with optional filtering.
 
 Examples:
   pinner list

pkg/cli/operations.go

@@ -28,7 +28,7 @@ Operations track server-side processing of your requests. Each operation has a s
 Examples:
   pinner operations list
   pinner operations list --status running
-  pinner operations list --cid QmHash --limit 20
+  pinner operations list --cid bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --limit 20
   pinner operations get 42
   pinner operations get 42 --watch`,
 		Commands: []*cli.Command{
@@ -43,13 +43,14 @@ func newOperationsListCommand() *cli.Command {
 		Name:  "list",
 		Usage: "List account operations",
 		Description: `List your account operations with optional filtering.
+Operations track server-side processing of your requests (uploads, pins, etc.).
 
 Examples:
   pinner operations list
   pinner operations list --status running
   pinner operations list --operation upload
   pinner operations list --protocol ipfs
-  pinner operations list --cid QmHash
+  pinner operations list --cid bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e
   pinner operations list --limit 20
   pinner operations list --watch`,
 		Flags: []cli.Flag{

pkg/cli/pin.go

@@ -14,18 +14,18 @@ func newPinCommand() *cli.Command {
 		Name:     "pin",
 		Category: "Pinning",
 		Usage:    "Pin existing content by CID (see: pinner pins add)",
-		Description: `Pin content that is already on IPFS by providing its CID.
+		Description: `Shortcut for 'pinner pins add'. Pin existing IPFS content by CID.
 Multiple CIDs can be provided as arguments, read from a file using --file, or piped from stdin.
 
 Examples:
-  pinner pin QmHash
-  pinner pin QmHash --name "my file"
-  pinner pin QmHash --no-wait
-  pinner pin QmHash1 QmHash2 QmHash3 --parallel 5
+  pinner pin bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e
+  pinner pin bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --name "my file"
+  pinner pin bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --no-wait
+  pinner pin bafybeig...abc bafybeig...def bafybeig...ghi --parallel 5
   pinner pin --file cids.txt
-  echo "QmHash" | pinner pin
+  echo "bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e" | pinner pin
   pinner pin --file cids.txt --continue --parallel 10
-  pinner pin QmHash --dry-run`,
+  pinner pin bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --dry-run`,
 		ArgsUsage: "<cid...>",
 		Flags: []cli.Flag{
 			NameFlag("Custom name for the pin"),

pkg/cli/pinning_client.go

@@ -265,7 +265,7 @@ func (s *PinningServiceDefault) Unpin(ctx context.Context, cidStr string, confir
 	s.output.PrintVerbosef("Using API endpoint: %s", s.apiEndpoint)
 
 	if !confirm {
-		s.output.Printfln("Use --confirm to unpin CID: %s", cidStr)
+		s.output.Printfln("Use --force to unpin CID: %s", cidStr)
 		return NewUnpinResult(cidStr), nil
 	}
 

pkg/cli/pins.go

@@ -13,12 +13,12 @@ func newPinsCommand() *cli.Command {
 removing, listing, checking status, and updating pin metadata.
 
 Examples:
-  pinner pins add QmHash --name "my file"
-  pinner pins add QmHash --meta owner=alice --meta env=prod
-  pinner pins rm QmHash --confirm
+  pinner pins add bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --name "my file"
+  pinner pins add bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --meta owner=alice --meta env=prod
+  pinner pins rm bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --force
   pinner pins ls --status pinned
-  pinner pins status QmHash
-  pinner pins update QmHash --meta owner=bob`,
+  pinner pins status bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e
+  pinner pins update bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --meta owner=bob`,
 		Commands: []*cli.Command{
 			newPinsAddCommand(),
 			newPinsRmCommand(),

pkg/cli/pins_add.go

@@ -16,13 +16,13 @@ func newPinsAddCommand() *cli.Command {
 Optionally set metadata key-value pairs at pin time using --meta.
 
 Examples:
-  pinner pins add QmHash
-  pinner pins add QmHash --name "my file"
-  pinner pins add QmHash --no-wait
-  pinner pins add QmHash --meta owner=alice --meta env=prod
-  pinner pins add QmHash1 QmHash2 QmHash3 --parallel 5
+  pinner pins add bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e
+  pinner pins add bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --name "my file"
+  pinner pins add bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --no-wait
+  pinner pins add bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --meta owner=alice --meta env=prod
+  pinner pins add bafybeig...abc bafybeig...def bafybeig...ghi --parallel 5
   pinner pins add --file cids.txt
-  pinner pins add QmHash --dry-run`,
+  pinner pins add bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --dry-run`,
 		ArgsUsage: "<cid...>",
 		Flags: []cli.Flag{
 			NameFlag("Custom name for the pin"),

pkg/cli/pins_rm.go

@@ -13,11 +13,11 @@ func newPinsRmCommand() *cli.Command {
 		Description: `Remove a pin by its CID, or remove all pins with --all.
 
 Examples:
-  pinner pins rm QmHash
-  pinner pins rm QmHash --confirm
-  pinner pins rm QmHash1 QmHash2 QmHash3 --confirm
-  pinner pins rm --file cids.txt --confirm
-  pinner pins rm QmHash --dry-run
+  pinner pins rm bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e
+  pinner pins rm bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --force
+  pinner pins rm bafybeig...abc bafybeig...def bafybeig...ghi --force
+  pinner pins rm --file cids.txt --force
+  pinner pins rm bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --dry-run
   pinner pins rm --all --force
   pinner pins rm --all --status failed --force`,
 		ArgsUsage: "<cid...>",

pkg/cli/pins_status.go

@@ -10,13 +10,13 @@ func newPinsStatusCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "status",
 		Usage: "Get pin status for CID (see: pinner status)",
-		Description: `Check the status of a pin to see if it has been completed.
+		Description: `Check whether a pin has completed.
 If the pin is not found, account operations are checked as a fallback.
 
 Examples:
-  pinner pins status QmHash
-  pinner pins status QmHash --watch
-  pinner pins status QmHash --json`,
+  pinner pins status bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e
+  pinner pins status bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --watch
+  pinner pins status bafybeigqaforwjgcx45jnh7dgyfgqqm2lei4hurrrnsizrpgyxz3egtd7e --json`,
 		ArgsUsage: "<cid>",
 		Flags: []cli.Flag{
 			&cli.BoolFlag{