CLI Guide

This guide describes the changes between the v4 and v5 versions of the command line.

Caution

Before upgrading to v5, please run the command lego migrate.

This command will migrate the file structure to the new one.

This is a requirement.

This command will not work if you were using the deprecated --filename flag.

If you need help, please open a discussion.

Commands

The global flags have been moved to flags of the commands.

Example:

# Before
lego --dns foo -d '*.example.com' -d example.com run
# After
lego run --dns foo -d '*.example.com' -d example.com

The command renew has been removed because the command run is able to renew certificates.

The command list has been removed and replaced by accounts list and certificates list.

The command revoke has been removed and replaced by certificates revoke.

Flags

Some flags have been changed, renamed or removed:

v4 Change Type v5
--disable-cn removed and replaced --enable-cn
--dns.disable-cp removed and replaced --dns.propagation.wait
--dns.propagation-wait renamed --dns.propagation.wait
--dns.propagation-disable-ans renamed --dns.propagation.disable-ans
--dns.propagation-rns removed and replaced --dns.propagation.disable-rns
--dns-timeout renamed --dns.timeout
--kid renamed --eab-kid
--hmac renamed --eab-hmac
--days renamed --renew-days1
--dynamic removed This is the default behavior now.
--run-hook renamed --deploy-hook
--renew-hook renamed --deploy-hook
--tls.port renamed --tls.address
--http.port renamed --http.address
--pfx.pass renamed --pfx.password

Directory structure

The directory structure has been changed.

​
.
├── accounts
│   └── <server-name-1>
│       ├── <account-name-1>
│       │   ├── account.json
│       │   └── keys
│       │       └── <account-name-1>.key
│       └── <account-name-2>
│           ├── account.json
│           └── keys
│               └── <account-name-2>.key
└── certificates
    ├── example.com.crt
    ├── example.com.issuer.crt
    ├── example.com.json
    ├── example.com.key
    ├── example.org.crt
    ├── example.org.issuer.crt
    ├── example.org.json
    └── example.org.key
.
├── accounts
│   └── <server-name-1>
│       ├── <account-name-1>
│       │   ├── account.json
│       │   └── <account-name-1>.key
│       └── <account-name-2>
│           ├── account.json
│           └── <account-name-2>.key
└── certificates
    ├── example.com.crt
    ├── example.com.issuer.crt
    ├── example.com.json
    ├── example.com.key
    ├── example.org.crt
    ├── example.org.issuer.crt
    ├── example.org.json
    └── example.org.key

Environment variables

The following environment variables have been removed without replacement:

  • SELECTEL_BASE_URL
  • VSCALE_BASE_URL

The following environment variables related to the hook have been renamed:

v4 v5
LEGO_ACCOUNT_EMAIL LEGO_HOOK_ACCOUNT_EMAIL
LEGO_CERT_DOMAIN LEGO_HOOK_CERT_NAME
LEGO_CERT_PATH LEGO_HOOK_CERT_PATH
LEGO_CERT_KEY_PATH LEGO_HOOK_CERT_KEY_PATH
LEGO_CERT_PEM_PATH LEGO_HOOK_CERT_PEM_PATH
LEGO_CERT_PFX_PATH LEGO_HOOK_CERT_PFX_PATH

CommonName

The support of the common name is disabled by default.

PEM encoding

Lego uses PKCS#8 instead of PKCS#1 for PEM encoding.

Default resolver/nameserver fallbacks

The default resolver/nameserver fallbacks have been changed.

​
  • google-public-dns-a.google.com:53
  • google-public-dns-b.google.com:53
  • 1.1.1.1:53
  • 1.0.0.1:53
  • [2606:4700:4700::1111]:53
  • [2606:4700:4700::1001]:53

  1. By default, the renewal time is dynamically computed (the behavior of the previous --dynamic flag). ↩︎