Documentation/public-inbox-learn.pod |  2 +-
 Documentation/public-inbox-mda.pod   |  2 +-
 script/public-inbox-learn            | 23 ++++++++++++++++++-----
 script/public-inbox-mda              | 18 ++++++++++++++----

diff --git a/Documentation/public-inbox-learn.pod b/Documentation/public-inbox-learn.pod
index cd9bf2782ad74bae8cbb90544aef7618d7408b22..94c96fd5a469f26ec9b4d22f3dff670244b42158 100644
--- a/Documentation/public-inbox-learn.pod
+++ b/Documentation/public-inbox-learn.pod
@@ -4,7 +4,7 @@ public-inbox-learn - spam trainer and remover for public-inbox
 
 =head1 SYNOPSIS
 
-B<public-inbox-learn> <spam|ham|rm> E<lt>MESSAGE
+  public-inbox-learn <spam|ham|rm> </path/to/RFC2822_message
 
 =head1 DESCRIPTION
 
diff --git a/Documentation/public-inbox-mda.pod b/Documentation/public-inbox-mda.pod
index 99c9053d35949496491c36274dad1d9d3f164c33..a5e353e5aaab53cd6ccdca55f6f4578fab0b0436 100644
--- a/Documentation/public-inbox-mda.pod
+++ b/Documentation/public-inbox-mda.pod
@@ -4,7 +4,7 @@ public-inbox-mda - mail delivery agent for public-inbox
 
 =head1 SYNOPSIS
 
-B<public-inbox-mda> E<lt>MESSAGE
+  public-inbox-mda </path/to/RFC2822_message
 
 =head1 DESCRIPTION
 
diff --git a/script/public-inbox-learn b/script/public-inbox-learn
index 5cd08d490bf0273bce85ce4d148bdb09035ad288..fb2d86ec141ff11741d6681975d9a0feb7579c44 100755
--- a/script/public-inbox-learn
+++ b/script/public-inbox-learn
@@ -4,9 +4,22 @@ # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 #
 # Used for training spam (via SpamAssassin) and removing messages from a
 # public-inbox
-my $usage = "$0 <spam|ham|rm> </path/to/message";
+my $help = <<EOF;
+usage: public-inbox-learn [OPTIONS] [spam|ham|rm] </path/to/RFC2822_message
+
+required action argument:
+
+   spam  unindex the message and train as spam
+     rm  remove the message without training as spam
+    ham  index the message (based on To:/Cc: headers) and train as ham
+
+options:
+
+  --all  scan all inboxes on `rm'
+
+See public-inbox-learn(1) man page for full documentation.
+EOF
 use strict;
-use warnings;
 use PublicInbox::Config;
 use PublicInbox::InboxWritable;
 use PublicInbox::Eml;
@@ -14,11 +27,11 @@ use PublicInbox::Address;
 use PublicInbox::Spamcheck::Spamc;
 use Getopt::Long qw(:config gnu_getopt no_ignore_case auto_abbrev);
 my %opt = (all => 0);
-GetOptions(\%opt, 'all') or die "bad command-line args\n";
+GetOptions(\%opt, qw(all help|h)) or die $help;
 
-my $train = shift or die "usage: $usage\n";
+my $train = shift or die $help;
 if ($train !~ /\A(?:ham|spam|rm)\z/) {
-	die "`$train' not recognized.\nusage: $usage\n";
+	die "`$train' not recognized.\n$help";
 }
 die "--all only works with `rm'\n" if $opt{all} && $train ne 'rm';
 
diff --git a/script/public-inbox-mda b/script/public-inbox-mda
index 02ca343163eaf00658b8081f025695f94b6c2e58..3ed5abb6d910dfb76b586a5fbd4dfb4ca9dfa024 100755
--- a/script/public-inbox-mda
+++ b/script/public-inbox-mda
@@ -3,11 +3,21 @@ # Copyright (C) 2013-2020 all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 #
 # Mail delivery agent for public-inbox, run from your MTA upon mail delivery
+my $help = <<EOF;
+usage: public-inbox-mda [OPTIONS] </path/to/RFC2822_message
+
+options:
+
+  --no-precheck  skip internal checks for spam messages
+
+See public-inbox-mda(1) man page for full documentation.
+EOF
 use strict;
-use warnings;
-my $usage = 'public-inbox-mda [OPTIONS] < rfc2822_message';
-my $precheck = grep(/\A--no-precheck\z/, @ARGV) ? 0 : 1;
-my ($ems, $emm);
+use Getopt::Long qw(:config gnu_getopt no_ignore_case auto_abbrev);
+my ($ems, $emm, $show_help);
+my $precheck = 1;
+GetOptions('precheck!' => \$precheck, 'help|h' => \$show_help) or
+	do { print STDERR $help; exit 1 };
 
 my $do_exit = sub {
 	my ($code) = shift;