Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@avelor/ttl) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

ttl

SSL certificate expiry checker. Warns before certs expire. CI-friendly.

demo

  ✓  avelor.es        76d             expires 2026-08-17 · Let's Encrypt
  ✓  api.avelor.es    76d             expires 2026-08-17 · Let's Encrypt
  ✖  old.avelor.es    expired 3d ago  expires 2026-05-30 · Let's Encrypt

  ✖ 1 cert below threshold (30d).

Install

npm install -g @avelor/ttl

Requires Node.js 18+.

Usage

ttl                            # scan using .ttl.yml in current directory
ttl avelor.es api.avelor.es    # check domains directly
ttl --threshold 14             # warn when less than 14 days remain
ttl --format github            # GitHub Actions annotations

Exit code is 0 if all certs are above the threshold, 1 if any are not — including connection errors.

.ttl.yml

threshold: 30
timeout: 10000

domains:
  - avelor.es
  - api.avelor.es
  - app.avelor.es

Domains passed as CLI arguments override the config file list entirely.

Field	Description	Default
`threshold`	Days remaining before a cert is considered a violation	`30`
`timeout`	Connection timeout per domain, in milliseconds	`10000`
`domains`	List of domains to check (port 443)	—

CI / GitHub Actions

Use --format github to emit native annotations that appear inline on the PR or workflow summary.

- name: Check SSL certificates
  run: npx @avelor/ttl --format github

Output:

::error::ttl: old.avelor.es expires in -3d (threshold: 30d)
:⚠️:ttl: staging.avelor.es expires in 12d (threshold: 30d)

Errors for certs below the threshold. Warnings for certs within 1.5× the threshold.

For scheduled monitoring, run it as a cron job:

on:
  schedule:
    - cron: '0 9 * * 1'  # every Monday at 9am

Options

--threshold <days>   Warn when cert expires within N days (default: 30)
--format <type>      human (default), json, github
--config <path>      Path to config file (default: .ttl.yml)
-v, --version
-h, --help

JSON output

ttl --format json | jq '.[] | select(.violation)'

Each entry:

{
  "domain": "avelor.es",
  "daysLeft": 76,
  "expiresAt": "2026-08-17",
  "issuer": "Let's Encrypt",
  "violation": false
}

On connection errors, error replaces the cert fields and violation is true.

How it works

ttl opens a TLS connection to each domain on port 443, reads the peer certificate, and calculates the number of days until valid_to. All domains are checked in parallel. No external dependencies — uses Node's built-in tls module.

License

MIT