Implement our fancy new --help output #3883

pde · 2016-12-09T03:48:26Z

The top level help is now:

  certbot [SUBCOMMAND] [options] [-d DOMAIN] [-d DOMAIN] ...

Certbot can obtain and install HTTPS/TLS/SSL certificates.  By default,
it will attempt to use a webserver both for obtaining and installing the
cert. The most common SUBCOMMANDS and flags are:

obtain, install, and renew certificates:
    (default) run   Obtain & install a cert in your current webserver
    certonly        Obtain or renew a cert, but do not install it
    renew           Renew all previously obtained certs that are near expiry
   -d DOMAINS       Comma-separated list of domains to obtain a cert for

  --apache          Use the Apache plugin for authentication & installation
  --standalone      Run a standalone webserver for authentication
  --nginx           Use the Nginx plugin for authentication & installation
  --webroot         Place files in a server's webroot folder for authentication
  --manual          Obtain certs interactively, or using shell script hoooks

   -n               Run non-interactively
  --test-cert       Obtain a test cert from a staging server
  --dry-run         Test "renew" or "certonly" without saving any certs to disk

manage certificates:
    certificates    Display information about certs you have from Certbot
    revoke          Revoke a certificate (supply --cert-path)

manage your account with Let's Encrypt:
    register        Create a Let's Encrypt ACME account
  --agree-tos       Agree to the ACME server's Subscriber Agreement
   -m EMAIL         Email address for important account notifications

More detailed help:

  -h, --help [TOPIC]    print this message, or detailed help on a topic;
                        the available TOPICS are:

   all, automation, commands, paths, security, testing, or any of the
   subcommands or plugins (certonly, renew, install, register, nginx,
   apache, standalone, webroot, script, etc.)

There is also a cerbot -h commands, which produces:


  certbot [SUBCOMMAND] [options] [-d DOMAIN] [-d DOMAIN] ...

Certbot can obtain and install HTTPS/TLS/SSL certificates.  By default,
it will attempt to use a webserver both for obtaining and installing the
cert. The full list of available SUBCOMMANDS is:

run (default)      Obtain/renew a certificate, and install it
certonly           Obtain or renew a certificate, but do not install it
renew              Renew all certificates (or one specifed with --cert-name)
certificates       List all certificates managed by Certbot
revoke             Revoke a certificate specified with --cert-path
revoke             Change a certificate's name (for management purposes)
register           Register for account with Let's Encrypt / other ACME server
install            Install an arbitrary cert in a server
config_changes     Show changes that Certbot has made to server configurations
rollback           Roll back server conf changes made during cert installation
plugins            List plugins that are installed and available on your system
update_symlinks    Recreate symlinks in your /live/ directory

You can get more help on a specific subcommand with --help SUBCOMMAND

It's also possible to customise the help more for any given subcommand; I've done that for run, certonly, and renew. For instance, certbot -h renew now produces:

usage: 

  certbot renew [--cert-name NAME] [options]

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIG_FILE, --config CONFIG_FILE
                        path to config file (default: /etc/letsencrypt/cli.ini
                        and ~/.config/letsencrypt/cli.ini) (default: None)

renew:
  The 'renew' subcommand will attempt to renew all certificates (or more
  precisely, certificate lineages) you have previously obtained if they are
  close to expiry, and print a summary of the results. By default, 'renew'
  will reuse the options used to create obtain or most recently successfully
  renew each certificate lineage. You can try it with `--dry-run` first. For
  more fine-grained control, you can renew individual lineages with the
  `certonly` subcommand. Hooks are available to run commands before and
  after renewal; see https://certbot.eff.org/docs/using.html#renewal for
  more information on these.

  --dry-run             Perform a test run of the client, obtaining test
                        (invalid) certs but not saving them to disk. This can
                        currently only be used with the 'certonly' and 'renew'
                        subcommands. Note: Although --dry-run tries to avoid
                        making any persistent changes on a system, it is not
                        completely side-effect free: if used with webserver
                        authenticator plugins like apache and nginx, it makes
                        and then reverts temporary config changes in order to
                        obtain test certs, and reloads webservers to deploy
                        and then roll back those changes. It also calls --pre-
                        hook and --post-hook commands if they are defined
                        because they may be necessary to accurately simulate
                        renewal. --renew-hook commands are not called.
                        (default: False)
  --force-renewal, --renew-by-default
                        If a certificate already exists for the requested
                        domains, renew it now, regardless of whether it is
                        near expiry. (Often --keep-until-expiring is more
                        appropriate). Also implies --expand. (default: False)
  --allow-subset-of-names
                        When performing domain validation, do not consider it
                        a failure if authorizations can not be obtained for a
                        strict subset of the requested domains. This may be
                        useful for allowing renewals for multiple domains to
                        succeed even if some domains no longer point at this
                        system. This option cannot be used with --csr.
                        (default: False)
  -q, --quiet           Silence all output except errors. Useful for
                        automation via cron. Implies --non-interactive.
                        (default: False)
  --preferred-challenges PREF_CHALLS
                        A sorted, comma delimited list of the preferred
                        challenge to use during authorization with the most
                        preferred challenge listed first (Eg, "dns" or "tls-
                        sni-01,http,dns"). Not all plugins support all
                        challenges. See
                        https://certbot.eff.org/docs/using.html#plugins for
                        details. ACME Challenges are versioned, but if you
                        pick "http" rather than "http-01", Certbot will select
                        the latest version automatically. (default: [])
  --pre-hook PRE_HOOK   Command to be run in a shell before obtaining any
                        certificates. Intended primarily for renewal, where it
                        can be used to temporarily shut down a webserver that
                        might conflict with the standalone plugin. This will
                        only be called if a certificate is actually to be
                        obtained/renewed. (default: None)
  --post-hook POST_HOOK
                        Command to be run in a shell after attempting to
                        obtain/renew certificates. Can be used to deploy
                        renewed certificates, or to restart any servers that
                        were stopped by --pre-hook. This is only run if an
                        attempt was made to obtain/renew a certificate.
                        (default: None)
  --renew-hook RENEW_HOOK
                        Command to be run in a shell once for each
                        successfully renewed certificate. For this command,
                        the shell variable $RENEWED_LINEAGE will point to the
                        config live subdirectory containing the new certs and
                        keys; the shell variable $RENEWED_DOMAINS will contain
                        a space-delimited list of renewed cert domains
                        (default: None)
  --disable-hook-validation
                        Ordinarily the commands specified for --pre-hook
                        /--post-hook/--renew-hook will be checked for
                        validity, to see if the programs being run are in the
                        $PATH, so that mistakes can be caught early, even when
                        the hooks aren't being run just yet. The validation is
                        rather simplistic and fails if you use more advanced
                        shell constructs, so you can use this switch to
                        disable it. (default: True)

- Currently exceptions are often caught and burried in log files, even if this flag is provided!

* Parallalelise nosetests from tox * Parallelise even more things, break even more things * Now unbreak all the tests that aren't ready for ||ism * Try to pass tests! - Remove non-working hack in reporter_test - also be selective about ||ism in the cover environment * Try again * certbot-apache tests also work, given enough time * Nginx may need more time in Travis's cloud * Unbreak reporter_test under ||ism * More timeout * Working again? * This goes way faster * Another big win * Split a couple more large test suites * A last improvement * More ||ism! * ||ise lint too * Allow nosetests to figure out how many cores to use * simplify merge * Mark the new CLI tests as ||izable * Simplify reporter_test changes * Rationalise ||ism flags * Re-up coverage * Clean up reporter tests * Stop modifying testdata during tests * remove unused os

* Begin making "certbot certificates" future safe * Handle the case where a renewal conf file has no "server" entry

Also, update nginx not installed CLI hint

- subcommands now get their own usage headings if they want them - added "certbot -h commands"

pde · 2016-12-09T19:05:18Z

This includes #3877 only because I was using it while writing this branch, but it's going to be hard to rebase out due to subsequent merges...

ohemorange

Niiiice! Were we going to add a manage help group, or did we decide not to, or is that coming in a future PR?

ohemorange · 2016-12-09T22:34:29Z

certbot/cli.py

-  --authenticator standalone --installer apache
+manage certificates:
+    certificates    Display information about certs you have from Certbot
+    revoke          Revoke a certificate (supply --cert-path)


ohemorange · 2016-12-09T23:31:43Z

certbot/cli.py

+        "short": "Revoke a certificate specified with --cert-path",
+        "opts": "Options for revocation of certs"
+    }),
+    ("revoke", {


"rename" not "revoke"

ohemorange · 2016-12-09T23:52:18Z

certbot/cli.py

+        for verb, props in VERB_HELP:
+            padding = (longest - len(verb)) + 4
+            doc = props.get("short", "")
+            text += verb + " " * padding + doc + "\n"


For extra fancy: text += '{0:<{length}} {1}\n'.format(verb, doc, length=longest)

ohemorange · 2016-12-09T23:59:12Z

certbot/cli.py

+#        both for "cerbot -h SUBCOMMAND" and "certbot -h all"
+# usage: an optional string that overrides the header of "certbot -h SUBCOMMAND"
+VERB_HELP = [
+    ("run (default)", {


Can we alphabetize these, now that they're available on more of a reference page than a "most important first" help page?

ohemorange · 2016-12-10T00:00:17Z

certbot/cli.py

+    }),
+    ("update_symlinks", {
+        "short": "Recreate symlinks in your /live/ directory",
+        "opts": ("Recreates cert and key symlinks in {0}, if you changed them by hand, "


nit: these commas do not belong.

Looking at a grammatical ruleset about commas I believe the first one is advisable under rule 4A; the second is permitted under rule 3A though perhaps you could argue that the two clauses are sufficiently short that it could be omitted :)

pde · 2016-12-10T00:28:48Z

rename landed in master halfway through my work on this branch, so adding it now. manage should be added once it exists?

ohemorange · 2016-12-10T00:29:51Z

I thought we were just going to have manage as a help topic and not as a subcommand for now?

pde · 2016-12-10T00:47:48Z

You're totally right...

Also, implement a general mechanism for documenting subcommands within topics

pde · 2016-12-10T22:20:01Z

Ok I added a manage topic:

certbot --help manage
usage: 
  certbot [SUBCOMMAND] [options] [-d DOMAIN] [-d DOMAIN] ...

Certbot can obtain and install HTTPS/TLS/SSL certificates.  By default,
it will attempt to use a webserver both for obtaining and installing the
cert. 

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIG_FILE, --config CONFIG_FILE
                        path to config file (default: /etc/letsencrypt/cli.ini
                        and ~/.config/letsencrypt/cli.ini) (default: None)

manage:
  Various subcommands and flags are available for managing your
  certificates:

  certificates          List all certificates managed by Certbot
  renew                 Renew all certificates (or one specifed with --cert-
                        name)
  revoke                Revoke a certificate specified with --cert-path
  rename                Change a certificate's name (for management purposes)
  --cert-name CERTNAME  Certificate name to apply. Only one certificate name
                        can be used per Certbot run. To see certificate names,
                        run 'certbot certificates'.If there is no existing
                        certificate with this name and domains are requested,
                        create a new certificate with this name. (default:
                        None)
  --updated-cert-name NEW_CERTNAME
                        New name for the certificate. Must be a valid
                        filename. (default: None)
  --cert-path CERT_PATH
                        Path to where cert is saved (with auth --csr),
                        installed from or revoked. (default: None)

ohemorange

One typo that needs to be fixed, one opinion that doesn't. Otherwise looks great, I'll let you merge!

ohemorange · 2016-12-12T22:40:08Z

certbot/cli.py

@@ -788,15 +795,15 @@ def prepare_and_parse_args(plugins, args, detect_defaults=False):  # pylint: dis
             "multiple -d flags or enter a comma separated list of domains "
             "as a parameter.")
    helpful.add(
-        [None, "run", "certonly"],
+        [None, "run", "certonly", "manage"],
        "--cert-name", dest="certname",
        metavar="CERTNAME", default=None,
        help="Certificate name to apply. Only one certificate name can be used "
             "per Certbot run. To see certificate names, run 'certbot certificates'."


Missing a space after the period

ohemorange · 2016-12-12T22:41:44Z

certbot/cli.py

@@ -1051,9 +1058,7 @@ def _paths_parser(helpful):
        verb = helpful.help_arg

    cph = "Path to where cert is saved (with auth --csr), installed from or revoked."


Is that a lack of oxford comma I see? Probably because other parts are hogging all the commas.

pde and others added 16 commits December 6, 2016 16:28

Start reorganising -h output

9648c52

Fix the --debug flag

14c706d

- Currently exceptions are often caught and burried in log files, even if this flag is provided!

Explain the insanity

c1ec028

Improve the "certbot certificates" output (#3846)

cd4730a

* Begin making "certbot certificates" future safe * Handle the case where a renewal conf file has no "server" entry

Improvements, tweaks

75845c0

Capitalise on things

d62feec

Print the command summary for -h and -h all, but not otherwise

f2a83d7

Also, update nginx not installed CLI hint

Add a "certificates" help section

70a68bd

Clean up usage string construction

5a31ccf

Merge branch 'fix-debug' into cli-mainhelp-rebased

7e182a5

Greatly improve "certbot -h TOPIC"

3b394c7

- subcommands now get their own usage headings if they want them - added "certbot -h commands"

Merge remote-tracking branch 'origin/master' into cli-mainhelp-rebased

249d525

A few more cli formatting tests

72b1c0c

Auto-populate the verb subgroups from the docs

886f209

Show the new help output

d106f32

pde added area: documentation area: ui / ux labels Dec 9, 2016

pde added 3 commits December 8, 2016 20:06

Lint, tweak

369cc73

More lint, and cleanup

8f9922e

Infinite lint

e43285a

pde requested a review from ohemorange December 9, 2016 19:04

pde assigned ohemorange Dec 9, 2016

ohemorange requested changes Dec 10, 2016

View reviewed changes

pde added 3 commits December 9, 2016 16:34

Add rename to command summary; sort "-h commands" output

25790e8

Use fancy string formatting

7bfb20b

More space

34cf9c0

pde added 2 commits December 10, 2016 11:56

Implement --help manage

bc6949b

Also, implement a general mechanism for documenting subcommands within topics

Remove one comma

bad3127

pde added this to the 0.10.0 milestone Dec 10, 2016

Only create weird parser structures if -h is provided :)

cffc5c1

pde added 2 commits December 10, 2016 14:20

Update sample cli out

ff6449d

Lint

d05efc2

ohemorange approved these changes Dec 12, 2016

View reviewed changes

ohemorange assigned pde and unassigned ohemorange Dec 12, 2016

pde added 2 commits December 12, 2016 16:25

Revert cli-help.txt to previous release version

4677e40

Grammar & style

593d156

pde merged commit 0464ba2 into master Dec 13, 2016

pde mentioned this pull request Dec 14, 2016

Improve simple --help output #3861

Closed

pde deleted the cli-mainhelp-rebased branch December 19, 2016 23:30

This was referenced Dec 23, 2016

certbot --help <subcommand> #3705

Closed

Dialog is sometimes ugly #2025

Closed

bmw mentioned this pull request Jan 3, 2017

Revamp register subcommand #3816

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implement our fancy new --help output #3883

Implement our fancy new --help output #3883

pde commented Dec 9, 2016

pde commented Dec 9, 2016

ohemorange left a comment

ohemorange Dec 9, 2016

pde Dec 10, 2016

ohemorange Dec 9, 2016

ohemorange Dec 9, 2016

ohemorange Dec 9, 2016

pde Dec 10, 2016

ohemorange Dec 10, 2016

pde Dec 10, 2016 •

edited

pde commented Dec 10, 2016

ohemorange commented Dec 10, 2016

pde commented Dec 10, 2016

pde commented Dec 10, 2016

ohemorange left a comment

ohemorange Dec 12, 2016

ohemorange Dec 12, 2016

		@@ -1051,9 +1058,7 @@ def _paths_parser(helpful):
		verb = helpful.help_arg

		cph = "Path to where cert is saved (with auth --csr), installed from or revoked."

Implement our fancy new --help output #3883

Implement our fancy new --help output #3883

Conversation

pde commented Dec 9, 2016

pde commented Dec 9, 2016

ohemorange left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pde Dec 10, 2016 • edited

Choose a reason for hiding this comment

pde commented Dec 10, 2016

ohemorange commented Dec 10, 2016

pde commented Dec 10, 2016

pde commented Dec 10, 2016

ohemorange left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pde Dec 10, 2016 •

edited