ttl

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

  ✓  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)
::warning::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