trackssl

Friendly command-line client for TrackSSL — monitor TLS/SSL certificate expiry from your terminal. A thin, human-first wrapper over the TrackSSL Public API: clean tables and ✓ Valid · expires in 71 days instead of raw JSON, with --json as the escape hatch for CI and scripts.

Install

Run it without installing:

npx trackssl list

Or install globally:

npm i -g trackssl
trackssl list

Requires Node.js ≥ 18.

Authenticate

Get a tk_live_… API key from your TrackSSL dashboard, then either log in once:

trackssl login        # hidden prompt, saves to ~/.config/trackssl/config.json (chmod 600)

…or pass it via the environment (handy in CI):

export TRACKSSL_API_KEY=tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Precedence: TRACKSSL_API_KEY env → saved config. To point at a non-default API, use --api-url <url>, TRACKSSL_API_URL, or the saved config (default: https://trackssl-seven.vercel.app).

Commands

| Command | What it does | |---|---| | trackssl login | Save and validate your API key. | | trackssl list | Boxed table of every monitored domain (issuer, expiry, status). | | trackssl status <domain> [--port] | Certificate detail block for one domain. | | trackssl add <domain> [--port 443] [--label <text>] | Start monitoring a domain. | | trackssl rm <domain> [--port] | Stop monitoring a domain. | | trackssl scan <domain> [--port] | Force a fresh scan and show the result. | | trackssl audit [--fail-under 7] [--scan] | Table + summary; exits 4 if anything is expired or expiring soon — the CI command. |

Examples

trackssl list
trackssl add shop.acme.com --label "Storefront"
trackssl status shop.acme.com
trackssl status api.acme.com --port 8443
trackssl scan shop.acme.com
trackssl rm shop.acme.com
trackssl audit --fail-under 14        # fail CI if any cert expires within 14 days
trackssl audit --scan                 # force fresh scans before auditing

JSON output

Every command accepts --json to print the raw API JSON (no colors, no table) — the script contract:

trackssl list --json | jq '.domains[].hostname'
trackssl audit --json                 # adds a `failed` array and still sets the exit code

Exit codes

audit (and every command) follows a stable exit-code contract so CI can branch on the result:

| Code | Meaning | |---|---| | 0 | Success. | | 1 | Generic runtime failure (e.g. duplicate, not found, rate limited). | | 2 | Usage error (bad arguments, ambiguous hostname — pass --port). | | 3 | Auth error (no key, rejected key, or read-only key on a write command). | | 4 | audit found cert problems (expired or expiring under --fail-under). | | 5 | Network error (couldn't reach the API). |

Publishing

This package is published to npm by an operator: pushing a cli-v* git tag triggers the .github/workflows/cli-release.yml workflow, which runs npm publish. It is not published on every merge.

License

MIT