spiry

README

Spiry

A simple tool for checking domain & TLS certificate expiration dates

Usage

Top-Level Usage

These options are common to all spiry subcommands:

$ spiry -h
Usage: spiry <command>

TLS & WHOIS expiration date lookup

Commands:
  domain         look up domain expiration date
  certificate    look up TLS certificate expiration date

Flags:
  -h, --help        Show context-sensitive help.
  -D, --debug       Enable debug mode
  -v, --version     display version information and exit
  -b, --bare        only display expiration date
  -j, --json        display output as JSON
  -u, --unix        display expiration date as UNIX timestamp
  -r, --rfc1123z    display expiration date as RFC1123Z timestamp
  -R, --rfc3339     display expiration date as RFC3339 timestamp

Run "spiry <command> --help" for more information on a command.

Domain Lookup Usage

$ spiry domain -h
Usage: spiry domain <domain>

look up domain expiration date

Arguments:
  <domain>    top-level domain name to look up

Flags:
  -h, --help             Show context-sensitive help.
  -D, --debug            Enable debug mode
  -v, --version          display version information and exit
  -b, --bare             only display expiration date
  -j, --json             display output as JSON
  -u, --unix             display expiration date as UNIX timestamp
  -r, --rfc1123z         display expiration date as RFC1123Z timestamp
  -R, --rfc3339          display expiration date as RFC3339 timestamp

  -s, --server=STRING    use <server> as specific whois server

Certificate Lookup Usage

$ spiry certificate -h
Usage: spiry certificate <address>

look up TLS certificate expiration date

Arguments:
  <address>    address to retrieve TLS certificate from

Flags:
  -h, --help           Show context-sensitive help.
  -D, --debug          Enable debug mode
  -v, --version        display version information and exit
  -b, --bare           only display expiration date
  -j, --json           display output as JSON
  -u, --unix           display expiration date as UNIX timestamp
  -r, --rfc1123z       display expiration date as RFC1123Z timestamp
  -R, --rfc3339        display expiration date as RFC3339 timestamp

  -n, --name=STRING    request TLS certificate for domain <name> instead of <address>

Outputs & Examples

Command output is straightforward:

$ spiry domain --bare --unix example.it
1696896000

$ spiry domain --bare example.it
2023-10-10T00:00:00+0000

$ spiry domain --json example.com
{
  "domainName": "example.com",
  "expiry": "2023-08-13T04:00:00+0000"
}

$ spiry domain --json --rfc3339 example.net
{
  "domainName": "example.net",
  "expiry": "2023-08-30T04:00:00Z"
}

$ spiry domain example.net
example.net	2023-08-30T04:00:00+0000

$ spiry domain "example.shh"
spiry: error: unable to find eTLD for domain example.shh: eTLD root "example.shh" is not publicly managed and cannot be looked up using `whois`

$ spiry domain "example.horse"
spiry: error: reserved domain record "example.horse" cannot be looked up

Error handling

Error messages are emitted in plaintext format to standard error. If the errors are generated during flag parsing, the help text will be emitted to standard error. WHOIS lookup errors will be emitted to standard error, without the help text.

$ ./build/spiry -j -b -u -r domain example.com 1>/dev/null
spiry: error: --bare and --json can't be used together

spiry: look up domain name expiration

usage: spiry [-b|-j] [-u|-r|-R] [-h|-v] [-s <server>] <domain>
  -s, --server string   use <server> as specific whois server
  -b, --bare            only display expiration date
  -j, --json            display output as JSON
  -u, --unix            display expiration date as UNIX time
  -r, --rfc1123z        display expiration date as RFC1123Z timestamp
  -R, --rfc3339         display expiration date as RFC3339 timestamp
  -v, --version         display version information and exit
  -h, --help            display this help and exit

environment variables:
  SPIRY_DEBUG:   print debug messages
$ ./build/spiry no-such-example.com 1>/dev/null
ERROR: domain record "no-such-example.com" not found

Caveats

spiry is provided as-is, with no assertions to correctness or completeness at this time.

Functionally, spiry is "fine" but it's a work in progress and like all moving targets, some of the interfaces and options may change as it grows. Once a proper versioned release is cut, this warning will likely be removed.

TO DO

• Move to GitHub Actions
• User-definable output, printf style?
  • Y'all like writing parsers? Because this will probably require a small parser.

License

spiry is licensed under the terms of the MIT License.