trackssl

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