diff --git a/internal/app/api.go b/internal/app/api.go
index 3bf3e36b..17ed5a4a 100644
--- a/internal/app/api.go
+++ b/internal/app/api.go
@@ -277,9 +277,9 @@ func (a *application) apiCommand() *cobra.Command {
 	}}
 	cmd.Flags().StringVarP(&method, "method", "X", "GET", "HTTP `method`")
 	cmd.Flags().StringVar(&input, "input", "", "Read the request body from a `file`, or stdin with -")
-	cmd.Flags().StringArrayVarP(&headerValues, "header", "H", nil, "Add a request header: `\"Name: value\"`")
-	cmd.Flags().StringArrayVarP(&raw, "raw-field", "f", nil, "Add a string field: `name=value`")
-	cmd.Flags().StringArrayVarP(&typed, "field", "F", nil, "Add a typed field: `name=value`; @FILE or @- reads a file or stdin")
+	cmd.Flags().StringArrayVarP(&headerValues, "header", "H", nil, "Add an HTTP request header in `name:value` format")
+	cmd.Flags().StringArrayVarP(&raw, "raw-field", "f", nil, "Add a string parameter in `key=value` format")
+	cmd.Flags().StringArrayVarP(&typed, "field", "F", nil, "Add a typed parameter in `key=value` format; @FILE or @- reads a file or stdin")
 	cmd.Flags().StringVar(&output, "output-file", "", "Write the complete response to a new `file`")
 	cmd.Flags().BoolVarP(&include, "include", "i", false, "Print the response status and headers to stderr")
 	cmd.Flags().BoolVar(&verbose, "verbose", false, "Print the request and the response status and headers to stderr")
diff --git a/internal/app/auth.go b/internal/app/auth.go
index cd077b49..11f07372 100644
--- a/internal/app/auth.go
+++ b/internal/app/auth.go
@@ -130,10 +130,11 @@ On a terminal without a method flag, tea asks for the instance, how to log in, w
 keep the token and whether git should use tea for the instance. Otherwise choose one
 method:
 
-  --with-token           read an access token from stdin, or ask for it on a terminal
-  --oauth, --web         authorize tea in a web browser
-  --ssh-key FILE         sign requests with an SSH private key
-  --ssh-agent-key, --ssh-agent-principal   sign requests with a key in ssh-agent
+  --with-token             read an access token from stdin, or ask for it on a terminal
+  --oauth, --web           authorize tea in a web browser
+  --ssh-key FILE           sign requests with an SSH private key
+  --ssh-agent-key FP       sign requests with the key of fingerprint FP in ssh-agent
+  --ssh-agent-principal P  sign requests with the ssh-agent certificate of principal P
 
 Create a token on the instance under Settings > Applications. Logging in to an account
 that tea already has replaces its stored credential after a confirmation (or with --yes).`,
diff --git a/internal/app/notifications.go b/internal/app/notifications.go
index 9e1422bd..a19d997c 100644
--- a/internal/app/notifications.go
+++ b/internal/app/notifications.go
@@ -48,12 +48,12 @@ list shows identify notification threads; they are not issue numbers.`}
 	}
 	group.AddCommand(a.notificationListCommand(scope), a.notificationWatchCommand(scope), a.notificationViewCommand(scope))
 	for _, mark := range []struct {
-		verb, status, filter, short, done, example string
+		verb, status, filter, short, ask, done, example string
 	}{
-		{"mark-read", "read", "unread", "Mark notifications as read", "Marked %s as read", "$ tea notification mark-read 28\n# Everything in one repository\n$ tea notification mark-read --all -R alice/project"},
-		{"mark-unread", "unread", "read", "Mark notifications as unread", "Marked %s as unread", "$ tea notification mark-unread 28 26"},
-		{"pin", "pinned", "unread", "Pin notifications", "Pinned %s", "$ tea notification pin 28"},
-		{"unpin", "read", "pinned", "Unpin notifications", "Unpinned %s", "$ tea notification unpin 28\n# Unpin everything\n$ tea notification unpin --all"},
+		{"mark-read", "read", "unread", "Mark notifications as read", "Mark all %s as read?", "Marked %s as read", "$ tea notification mark-read 28\n# Everything in one repository\n$ tea notification mark-read --all -R alice/project"},
+		{"mark-unread", "unread", "read", "Mark notifications as unread", "Mark all %s as unread?", "Marked %s as unread", "$ tea notification mark-unread 28 26"},
+		{"pin", "pinned", "unread", "Pin notifications", "Pin all %s?", "Pinned %s", "$ tea notification pin 28"},
+		{"unpin", "read", "pinned", "Unpin notifications", "Unpin all %s?", "Unpinned %s", "$ tea notification unpin 28\n# Unpin everything\n$ tea notification unpin --all"},
 	} {
 		var all bool
 		var filters []string
@@ -100,7 +100,7 @@ list shows identify notification threads; they are not issue numbers.`}
 				}
 				what := notificationsWith(filters) + " " + s.where
 				if settings, err := a.deps.Settings.Load(); err == nil && a.policy(settings).CanPrompt(a.deps.Streams) {
-					if err := a.confirmAction(cmd, terminal.Confirmation{Prompt: fmt.Sprintf("%s all %s?", strings.Replace(mark.done, " %s", "", 1), what), DefaultYes: true}); err != nil {
+					if err := a.confirmAction(cmd, terminal.Confirmation{Prompt: fmt.Sprintf(mark.ask, what), DefaultYes: true}); err != nil {
 						return err
 					}
 				}
@@ -120,7 +120,7 @@ list shows identify notification threads; they are not issue numbers.`}
 			},
 		}
 		command.Flags().BoolVar(&all, "all", false, "Apply to every notification that matches --status in the scope")
-		command.Flags().StringSliceVar(&filters, "status", nil, "With --all, the statuses to change")
+		command.Flags().StringSliceVar(&filters, "status", nil, "With --all, the statuses to change: unread, read, pinned")
 		enumValues(command, "status", "unread", "read", "pinned")
 		command.Flags().StringVar(&before, "before", "", "With --all, only notifications updated before a date, timestamp, or duration such as 1h")
 		group.AddCommand(command)
@@ -131,9 +131,9 @@ list shows identify notification threads; they are not issue numbers.`}
 // notificationFilters registers the list filters of list and watch.
 func notificationFilters(cmd *cobra.Command, opts *services.NotificationOptions, updated *timeRange) {
 	pageFlags(cmd, &opts.Limit, &opts.Page)
-	cmd.Flags().StringSliceVar(&opts.Statuses, "status", []string{"unread", "pinned"}, "Only notifications with these statuses")
+	cmd.Flags().StringSliceVar(&opts.Statuses, "status", []string{"unread", "pinned"}, "Only notifications with these statuses: unread, read, pinned")
 	enumValues(cmd, "status", "unread", "read", "pinned")
-	cmd.Flags().StringSliceVar(&opts.Types, "type", nil, "Only notifications about these subjects")
+	cmd.Flags().StringSliceVar(&opts.Types, "type", nil, "Only notifications about these subjects: issue, pull, commit, repository")
 	enumValues(cmd, "type", "issue", "pull", "commit", "repository")
 	updated.register(cmd, "since", "Only notifications updated since a date, timestamp, or duration such as 24h", "before", "Only notifications updated before a date, timestamp, or duration such as 1h")
 }
diff --git a/internal/app/notifications_test.go b/internal/app/notifications_test.go
index 04f6cffc..1e8c0028 100644
--- a/internal/app/notifications_test.go
+++ b/internal/app/notifications_test.go
@@ -132,6 +132,11 @@ func TestNotificationMutationsReportWhatChanged(t *testing.T) {
 		require.Equal(t, tc.want, withoutANSI(diagnostics.String()), tc.args)
 	}
 	require.Equal(t, []string{"pinned", "read", "read", "all read"}, marks)
+	prompt := &scriptedPrompter{accept: true}
+	deps.Prompter, deps.Streams.InTTY, deps.Streams.ErrTTY = prompt, true, true
+	require.NoError(t, Execute(context.Background(), deps, []string{"notification", "pin", "--all"}))
+	require.Equal(t, []string{"Pin all unread notifications in your inbox?"}, prompt.confirmations)
+	deps.Streams.InTTY, deps.Streams.ErrTTY = false, false
 	marks = nil
 	out.Reset()
 	require.NoError(t, Execute(context.Background(), deps, []string{"notification", "view", "12"}))