Welcome to go-acme/lego v5

I am thrilled to announce go-acme/lego v5!

This is a major release that brings a completely redesigned CLI, and powerful new features.

🚀 What’s New

💍 One Command to Rule Them All: lego run

The biggest CLI change in v5 is the unification of run and renew into a single command: lego run.

It obtains a new certificate if none exists and renews it when it’s time. No more juggling two commands.

Flags have also moved: global flags are now command-level flags for clarity.

# Before (v4)
lego --dns cloudflare -d '*.example.com' -d example.com run

# After (v5)
lego run --dns cloudflare -d '*.example.com' -d example.com

See the documentation for more details.

📄 Configuration File Support

You can now drive lego entirely from a .lego.yml file, eliminating long command lines and making automation easier.

challenges:
  cf:
    dns:
      provider: cloudflare

certificates:
  my-cert:
    challenge: cf
    domains:
      - example.com
      - '*.example.com'

Then just run:

CLOUDFLARE_EMAIL="you@example.com" \
CLOUDFLARE_API_KEY="yourkey" \
lego

You can also use dotenv files to manage your credentials.

The configuration file supports everything: certificates, challenges, accounts, servers, hooks, and logging.

It can be validated by a JSON Schema.

See the documentation for more details.

🐙 New Commands for Account, Certificate, and Archive Management

v5 introduces dedicated subcommands for managing your lego data:

Accounts:

• lego accounts register: Register a new ACME account.
• lego accounts recover: Recover/import an existing account from a private key.
• lego accounts keyrollover: Rotate the account private key.
• lego accounts list: List all accounts managed by lego.

See the documentation for more details.

Certificates:

• lego certificates list: List all certificates with their status and expiration date.
• lego certificates revoke: Revoke one or all certificates.

See the documentation for more details.

Archives:

• lego archives list: List all backed-up accounts and certificates.
• lego archives restore: Restore a backup.

See the documentation for more details.

🔒 DNS-PERSIST-01 Challenge

lego now supports the new dns-persist-01 challenge type.

WARNING:

• The RFC is still a draft.
• This is currently not available in most CA production.

lego run -d 'example.com' --dns-persist

See the documentation for more details.

🧠 Smarter Certificate Renewal

EAB (External Account Binding) credentials are no longer required at renewal time, only at initial registration.

This simplifies automated renewal pipelines, especially with commercial CAs.

🪝 Pre-Hook, Deploy-Hook, and Post-Hook

lego v5 introduces three lifecycle hooks to let you run scripts around certificate issuance:

lego run -d 'example.com' --deploy-hook='./my-deploy-hook.sh'

Hooks receive rich context via environment variables (LEGO_HOOK_CERT_PATH, LEGO_HOOK_CERT_KEY_PATH, etc.).

With a Configuration File:

hooks:
  pre:
    command: './my-pre-hook.sh'
  deploy:
    command: './my-deploy-hook.sh'
  post:
    command: './my-post-hook.sh'

See the documentation for more details.

Don’t hesitate to share your hook scripts with the community.

🌐 IPv6-Only Support

For hosts running on IPv6-only networks, lego v5 can be configured to exclusively use the IPv6 network stack.

lego run -d 'example.com' --http --ipv6only

With a Configuration File:

networkStack: ipv6only

📰 Structured Logging with JSON Output

lego v5 introduces structured logging with support for text, colored (default), and json formats (useful for log collectors).

lego --log.format=json --log.level=info run -d 'example.com' --http

Note that --log.format and --log.level are global flags.

With a Configuration File:

log:
  level: info
  format: json

🏷️ CA Server Short-Codes

Instead of typing full ACME server URLs, you can now use short-codes for well-known CAs:

lego run --server='letsencrypt-staging' ...
lego run --server='zerossl' ...
lego run --server='googletrust' ...

A full list of supported short-codes is available in the documentation.

🗃️ 24 New DNS Providers

lego v5 adds support for 24 new DNS providers, bringing the total to over 210:

51DNS, Abion, Curanet, DanDomain, Dinahosting, DNS.services, DNScale, dnsla, EUsrv, Fornex, Gehirn, Gname, Katapult, NederHost, NGENIX, omg.lol, PointDNS/PointHQ, Rage4, ScanNet, Tele3, Veesp, Wannafind, Xinnet, Zilore.

See the documentation for more details.

♻️ Migrating from v4

v5 includes breaking changes to the CLI, directory structure, and the API of the library.

Before upgrading, run:

lego migrate

or

lego migrate --path /path/to/lego/storage

This migrates your storage directory to the new layout.

See the full migration guide for details on flags, environment variables, and other changes.

📦 Get lego v5

Download the latest release from the GitHub releases page or use your preferred package manager.

We’d love to hear your feedback.

❤️ Support lego

lego is an independent, free, and open-source project.

It takes a lot of time and effort to maintain: Maintaining lego is maintaining an ACME client library, a CLI, and about +200 DNS implementations.

If you find lego useful, please consider supporting me.

If you are a company, we have dedicated tiers.

Every contribution, however small, makes a real difference.

Thank you!