Say what each command needs in --help and config.example.yml

snapshot verify --help now says --deep needs the age private key, from
VAULTIK_AGE_SECRET_KEY or age_secret_key, as snapshot restore does.
Both now name the config key as well as the environment variable.

The help of snapshot create, list, purge, remove, prune, remote info
and remote nuke says which access to the destination it needs.
config.example.yml gains age_secret_key, and no longer tells the reader
to pipe age-keygen into grep, which discards the private key.

Only help strings and comments change.

Model: fable-5-1

internal/cli/snapshot.go

@@ -60,6 +60,21 @@ func NewSnapshotCommand() *cobra.Command {
 	return cmd
 }
 
+// snapshotCreateLong is the long help text of 'snapshot create'.
+const snapshotCreateLong = `Creates new snapshots of the configured directories.
+
+If snapshot names are provided, only those snapshots are created.
+If no names are provided, all configured snapshots are created.
+
+Needs at least one public key in age_recipients, and permission to write
+objects at the backup destination store. It does not need the age private
+key. With --prune it also needs permission to list, read and delete objects
+there.
+
+The config is read from the path given by --config or VAULTIK_CONFIG;
+otherwise from the platform config directory (~/.config/vaultik/config.yml
+on Linux), then /etc/vaultik/config.yml.`
+
 // newSnapshotCreateCommand creates the 'snapshot create' subcommand
 func newSnapshotCreateCommand() *cobra.Command {
 	opts := &vaultik.SnapshotCreateOptions{}
@@ -67,15 +82,8 @@ func newSnapshotCreateCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "create [snapshot-names...]",
 		Short: "Create new snapshots",
-		Long: `Creates new snapshots of the configured directories.
-
-If snapshot names are provided, only those snapshots are created.
-If no names are provided, all configured snapshots are created.
-
-The config is read from the path given by --config or VAULTIK_CONFIG;
-otherwise from the platform config directory (~/.config/vaultik/config.yml
-on Linux), then /etc/vaultik/config.yml.`,
-		Args: cobra.ArbitraryArgs,
+		Long:  snapshotCreateLong,
+		Args:  cobra.ArbitraryArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			err := opts.Validate()
 			if err != nil {
@@ -156,8 +164,15 @@ func newSnapshotListCommand() *cobra.Command {
 		Use:     "list",
 		Aliases: []string{"ls"},
 		Short:   "List all snapshots",
-		Long:    "Lists all snapshots with their ID, timestamp, and compressed size",
-		Args:    cobra.NoArgs,
+		Long: `Lists the snapshots in the local index and on the backup destination
+store, with their ID, timestamp, and sizes.
+
+Needs permission to list and read the destination store. It does not need
+the age private key. A snapshot that is only on the destination store is
+listed by its remote key, because its ID cannot be read without that key.
+If the destination store cannot be listed, the command warns and lists the
+local index alone.`,
+		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			return runVaultikApp(cmd, readOnly, false,
 				"Failed to list snapshots",
@@ -179,11 +194,19 @@ func newSnapshotPurgeCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "purge",
 		Short: "Purge old snapshots",
-		Long: `Removes snapshots based on age or count criteria.
+		Long: `Removes snapshots based on age or count criteria. Exactly one of
+--keep-latest and --older-than is required.
 
-Retention is per-snapshot-name: --keep-latest keeps the latest of each
-configured snapshot name, not the latest globally. Use --snapshot to
-restrict the operation to specific snapshot names.`,
+Retention is per-snapshot-name: --keep-latest keeps the latest snapshot of
+each name, not the latest globally. Use --snapshot to restrict the
+operation to specific snapshot names.
+
+Only snapshots in the local index are removed. Each one is removed from
+the local index and its metadata is deleted from the backup destination
+store. Blobs are not touched: run 'vaultik prune' afterwards.
+
+Needs permission to list and delete objects on the destination store. If
+the destination store cannot be listed, nothing is removed.`,
 		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			// Validate flags
@@ -222,14 +245,26 @@ func newSnapshotVerifyCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "verify <snapshot-id>",
 		Short: "Check a snapshot's blobs are present with the listed size",
-		Long: "Checks that every blob the snapshot's manifest lists is present\n" +
-			"in storage with the size the manifest records, and that the\n" +
-			"snapshot's encrypted database is present. It does not read blob\n" +
-			"contents; use --deep to download, decrypt, and re-hash every blob\n" +
-			"to detect corruption -- integrity, not who wrote it.\n\n" +
-			"The snapshot may be named by its ID or, on a host with no local\n" +
-			"index, by the remote key that 'snapshot list' prints for a\n" +
-			"remote-only snapshot (an unambiguous leading part is enough).",
+		Long: `Checks that every blob the snapshot's manifest lists is present
+in storage with the size the manifest records, and that the
+snapshot's encrypted database is present. It does not read blob
+contents and does not need the age private key.
+
+Use --deep to download, decrypt, and re-hash every blob to detect
+corruption -- integrity, not who wrote it.
+
+--deep requires the age private key, in the VAULTIK_AGE_SECRET_KEY
+environment variable or as age_secret_key in the config file; the
+environment variable wins. The variable may hold the whole age-keygen
+file (comments and all of its identities are accepted); read it from
+the file rather than typing the key, so it does not land in your shell
+history:
+
+  export VAULTIK_AGE_SECRET_KEY="$(cat vaultik_backup_private_key.txt)"
+
+The snapshot may be named by its ID or, on a host with no local
+index, by the remote key that 'snapshot list' prints for a
+remote-only snapshot (an unambiguous leading part is enough).`,
 		Args: requireSnapshotIDArg,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			snapshotID := args[0]
@@ -264,7 +299,10 @@ func newSnapshotVerifyCommand() *cobra.Command {
 		},
 	}
 
-	cmd.Flags().BoolVar(&opts.Deep, "deep", false, "Download and verify blob hashes")
+	cmd.Flags().BoolVar(&opts.Deep, "deep", false,
+		"Download, decrypt and re-hash every blob; requires the age private "+
+			"key in VAULTIK_AGE_SECRET_KEY, or as age_secret_key in the config "+
+			"file")
 	cmd.Flags().BoolVar(&opts.JSON, "json", false, "Output verification results as JSON")
 
 	return cmd
@@ -288,8 +326,10 @@ know about), which is what 'vaultik prune' does. The command prints the
 'vaultik prune' invocation to run as a follow-up only when it removed the
 snapshot's metadata from the destination store, and never under --json.
 
-An ID that names no snapshot in the local index or on the destination
-store is an error.
+The argument must be a snapshot ID: a remote key is not accepted. An ID
+that names no snapshot in the local index or on the destination store is
+an error. Needs permission to list and delete objects on the destination
+store, unless --local-only is given.
 
 Use --local-only to skip the remote half (e.g. when you want to forget a
 snapshot locally without touching the destination store); the snapshot