checkmy 0.1.2

# checkmy Usage Examples

A comprehensive guide with examples for all commands and options.

Text output is human-readable by default. Durations and sizes are shown with compact units when useful (for example: `918ms`, `1.24s`, `941.3 KiB`). DNS TTL values are rendered in compact time format (`w d h m s`), for example: `300 -> 5m`, `722 -> 12m2s`, `19297 -> 5h21m37s`.

For output design rules, see `docs/OUTPUT_STYLE.md`.

## Table of Contents

- [Output Conventions](#output-conventions)
- [Text vs JSON](#text-vs-json)
- [Smart Mode (Default)](#smart-mode-default)
- [dns - DNS Lookups](#dns---dns-lookups)
- [ip - IP Lookup](#ip---ip-lookup)
- [trace - Traceroute](#trace---traceroute)
- [cert - Certificate Inspection](#cert---certificate-inspection)
- [whois - WHOIS Lookups](#whois---whois-lookups)
- [connect - TCP/TLS Connectivity](#connect---tcptls-connectivity)
- [http - HTTP Healthcheck](#http---http-healthcheck)
- [port - Port Scanner](#port---port-scanner)
- [JSON Output & jq Examples](#json-output--jq-examples)
- [Scripting Examples](#scripting-examples)

## Output Conventions

- Text mode is for humans: concise sections, readable alignment, colored status cues.
- Time values include explicit units (`ms`, `s`, `m`, `h`).
- DNS TTL is displayed in compact human form (`w d h m s`) in text mode.
- Byte sizes are displayed using IEC units (`B`, `KiB`, `MiB`, `GiB`) when appropriate.

## Text vs JSON

- Use default text output for interactive troubleshooting.
- Use `--json` for automation and parsing.
- JSON keeps stable field semantics even when text layout evolves.

```bash
# Human-readable
checkmy http https://example.com

# Machine-readable
checkmy http https://example.com --json | jq '.response.status'
```

---

## Smart Mode (Default)

Run a full diagnostic audit by just passing a target. Smart mode auto-detects the target type and runs the appropriate checks.

### Domain Audit (Full 5-Phase)

```bash
# Full audit: DNS, WHOIS, Ports, TLS, HTTP
checkmy example.com

# Quick mode: skip WHOIS for faster results
checkmy example.com --quick

# Skip only WHOIS (same effect as --quick)
checkmy example.com --no-whois

# Deep mode: run traceroute after the audit
checkmy example.com --deep

# Combine quick + deep
checkmy example.com --quick --deep
```

### Target Type Detection

```bash
# Domain -> runs full 5-phase audit
checkmy google.com

# IPv4 address -> runs IP lookup (geolocation, ASN, reverse DNS)
checkmy 8.8.8.8

# IPv6 address -> runs IP lookup
checkmy 2606:4700:4700::1111

# host:port -> runs TCP/TLS connectivity test
checkmy example.com:443

# [ipv6]:port -> runs TCP/TLS connectivity test
checkmy "[2606:4700:4700::1111]:443"
```

### IP Version

```bash
# Force IPv4 resolution
checkmy example.com -4

# Force IPv6 resolution
checkmy example.com -6
```

### Audit Phases

The full domain audit runs these phases sequentially:

1. **DNS** — Resolves A/AAAA records. Required; aborts if it fails.
2. **WHOIS** — Domain registration info and expiration. Skipped with `--quick` or `--no-whois`.
3. **Ports** — Scans ports 80 and 443.
4. **TLS** — Certificate inspection. Only runs if port 443 is open.
5. **HTTP** — Tries HTTPS first, falls back to HTTP on failure.

Each phase reports one of three statuses:

| Status | Meaning |
|--------|---------|
| `ok` | Check passed |
| `warn` | Non-critical issue (e.g. WHOIS lookup failed, cert expiring in <30 days) |
| `fail` | Critical issue (e.g. DNS failed, cert expired, HTTP 5xx) |

### Output Options

```bash
# JSON output
checkmy example.com -j

# Disable colors
checkmy example.com --no-color
```

---

## dns - DNS Lookups

Perform DNS queries similar to `dig`.

TTL in text output uses compact human format (`w d h m s`). Use `--json` if you need raw numeric TTL seconds.

### Basic Usage

```bash
# Query all records (default type is ANY)
checkmy dns example.com
```

### Record Types

```bash
# A records (IPv4)
checkmy dns example.com -t A

# AAAA records (IPv6)
checkmy dns example.com -t AAAA

# MX records (mail servers)
checkmy dns example.com -t MX

# TXT records (SPF, DKIM, etc.)
checkmy dns example.com -t TXT

# NS records (name servers)
checkmy dns example.com -t NS

# ANY (all available records)
checkmy dns example.com -t ANY
```

### Custom DNS Server

```bash
# Use Google DNS
checkmy dns example.com -s 8.8.8.8

# Use Cloudflare DNS
checkmy dns example.com -s 1.1.1.1

# Use custom port
checkmy dns example.com -s 8.8.8.8 -p 53
```

### Protocol Options

```bash
# Force TCP instead of UDP
checkmy dns example.com --tcp

# Custom timeout (seconds)
checkmy dns example.com --timeout 10
```

### Output Options

```bash
# JSON output
checkmy dns example.com -j

# Verbose output
checkmy dns example.com -v

# Disable colors (for scripts)
checkmy dns example.com --no-color
```

---

## ip - IP Lookup

Look up geolocation, network, and reverse DNS information for an IP address.

### Basic Usage

```bash
# IPv4 lookup
checkmy ip 8.8.8.8

# IPv6 lookup
checkmy ip 2606:4700:4700::1111
```

### Options

```bash
# Custom timeout (seconds)
checkmy ip 1.1.1.1 --timeout 20

# JSON output
checkmy ip 8.8.8.8 -j

# Disable colors
checkmy ip 8.8.8.8 --no-color
```

### Smart Mode

IP lookup runs automatically when smart mode detects a bare IP address:

```bash
# Equivalent to: checkmy ip 1.1.1.1
checkmy 1.1.1.1
```

### Example Output

```text
IP Lookup  8.8.8.8

Location
  City           Mountain View
  Region         California
  Country        United States (US)
  Latitude       37.4056
  Longitude      -122.0775
  Postal Code    94043
  Timezone       America/Los_Angeles

Network
  Organization   Google LLC
  ASN            AS15169
  Network        8.8.8.0/24
  Hostname       dns.google

Completed in 342ms
```

---

## trace - Traceroute

Trace the route to a host, similar to `mtr`.

> **Note:** ICMP mode requires root/sudo privileges.

### Basic Usage

```bash
# ICMP traceroute (requires sudo)
sudo checkmy trace example.com

# TCP traceroute
checkmy trace example.com -P tcp
```

### Protocol Options

```bash
# ICMP (default, requires root)
sudo checkmy trace example.com -P icmp

# TCP SYN packets
checkmy trace example.com -P tcp

# UDP packets
checkmy trace example.com -P udp

# TCP/UDP with custom port
checkmy trace example.com -P tcp -p 443
checkmy trace example.com -P udp -p 53
```

### Trace Configuration

```bash
# Set maximum hops
sudo checkmy trace example.com --max-hops 20

# Set interval between probes
sudo checkmy trace example.com -i 500ms

# Report mode (non-interactive)
sudo checkmy trace example.com -r

# Report mode with custom cycles
sudo checkmy trace example.com -r -c 20
```

### Output Options

```bash
# JSON output
sudo checkmy trace example.com -j

# Verbose output
sudo checkmy trace example.com -v

# Disable colors
sudo checkmy trace example.com --no-color
```

---

## cert - Certificate Inspection

Inspect SSL/TLS certificates from any server.

### Basic Usage

```bash
# Inspect certificate on default port 443
checkmy cert example.com

# Inspect certificate on custom port
checkmy cert example.com -p 8443
```

### Certificate Chain

```bash
# Show full certificate chain
checkmy cert example.com --chain
```

### Connection Options

```bash
# Custom timeout
checkmy cert example.com --timeout 30
```

### Output Options

```bash
# JSON output
checkmy cert example.com -j

# Disable colors
checkmy cert example.com --no-color
```

---

## whois - WHOIS Lookups

Perform WHOIS lookups for domains and IP addresses.

### Basic Usage

```bash
# Domain lookup
checkmy whois example.com

# IP address lookup
checkmy whois 8.8.8.8
```

### Server Options

```bash
# Use a specific RDAP server (URL)
checkmy whois example.com -s https://rdap.verisign.com/com/v1

# Use a specific traditional WHOIS server (hostname)
checkmy whois example.com -s whois.verisign-grs.com

# Custom timeout
checkmy whois example.com --timeout 30
```

### Output Options

```bash
# Raw WHOIS response (unparsed)
checkmy whois example.com -r

# JSON output
checkmy whois example.com -j

# Disable colors
checkmy whois example.com --no-color
```

---

## connect - TCP/TLS Connectivity

Test raw TCP and TLS connections (telnet/netcat-like).

### Basic TCP Connection

```bash
# Simple TCP connection test
checkmy connect example.com 80

# Test SSH port
checkmy connect example.com 22

# Test with custom timeout (seconds)
checkmy connect example.com 80 --timeout 30
```

### TLS Connections

```bash
# Explicit TLS (auto-enabled for 443, 8443, etc.)
checkmy connect example.com 443 --tls

# TLS on non-standard port
checkmy connect example.com 8443 --tls

# Skip certificate validation (self-signed)
checkmy connect example.com 443 --tls --insecure
```

### IP Version

```bash
# Force IPv4
checkmy connect example.com 80 -4

# Force IPv6
checkmy connect example.com 80 -6
```

### Sending Data

```bash
# Send HTTP request
checkmy connect example.com 80 --send "GET / HTTP/1.0\r\n\r\n"

# Send with automatic CRLF
checkmy connect example.com 80 --send "GET / HTTP/1.0" --newline

# Send from file
checkmy connect example.com 80 --send-file request.txt

# Send hex data
checkmy connect example.com 6379 --send "2a310d0a24340d0a50494e470d0a" --hex
```

### Response Options

```bash
# Limit response bytes
checkmy connect example.com 80 --send "GET / HTTP/1.0\r\n\r\n" --max-bytes 1024

# Don't read response
checkmy connect example.com 25 --send "QUIT\r\n" --no-read

# Output response as hex
checkmy connect example.com 6379 --send "PING\r\n" --hex-output

# Read timeout
checkmy connect example.com 80 --read-timeout 10
```

### Output Options

```bash
# JSON output
checkmy connect example.com 443 --tls -j

# Disable colors
checkmy connect example.com 80 --no-color
```

---

## http - HTTP Healthcheck

Perform HTTP healthchecks with response validation.

### Basic Usage

```bash
# Simple GET request (https:// assumed)
checkmy http example.com

# Explicit HTTP
checkmy http http://example.com

# Explicit HTTPS
checkmy http https://example.com
```

### HTTP Methods

```bash
# GET (default)
checkmy http example.com -m GET

# HEAD (headers only)
checkmy http example.com -m HEAD

# POST
checkmy http example.com -m POST -d '{"key": "value"}'

# PUT
checkmy http example.com/resource -m PUT -d '{"updated": true}'

# DELETE
checkmy http example.com/resource/123 -m DELETE

# PATCH
checkmy http example.com/resource -m PATCH -d '{"field": "new_value"}'

# OPTIONS
checkmy http example.com -m OPTIONS
```

### Headers

```bash
# Single header
checkmy http example.com -H "Authorization: Bearer token123"

# Multiple headers
checkmy http example.com \
  -H "Authorization: Bearer token123" \
  -H "Content-Type: application/json" \
  -H "X-Custom-Header: value"

# User-Agent override
checkmy http example.com -H "User-Agent: MyApp/1.0"
```

### Request Body

```bash
# JSON body
checkmy http example.com -m POST \
  -H "Content-Type: application/json" \
  -d '{"username": "user", "password": "pass"}'

# Form data
checkmy http example.com -m POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=user&password=pass"
```

### Redirects

```bash
# Follow redirects (default: true)
checkmy http http://example.com -f

# Disable redirect following
checkmy http http://example.com --follow false

# Limit redirects
checkmy http http://example.com --max-redirects 5
```

### Content Validation

```bash
# Match string in response body
checkmy http example.com/health --match "ok"

# Match JSON field
checkmy http api.example.com/status --match '"status":"healthy"'
```

### TLS Options

```bash
# Skip certificate verification
checkmy http https://self-signed.local --insecure
```

### Timeout

```bash
# Custom timeout
checkmy http slow-api.example.com --timeout 30s

# Short timeout
checkmy http api.example.com --timeout 500ms
```

### Output Options

```bash
# JSON output
checkmy http example.com -j

# Disable colors
checkmy http example.com --no-color
```

---

## port - Port Scanner

Scan ports to check connectivity.

### Basic Usage

```bash
# Default: scan common ports (top 25)
checkmy port example.com

# Single port
checkmy port example.com -p 80

# Check if SSH is open
checkmy port example.com -p 22
```

### Port Specification

```bash
# Single port
checkmy port example.com -p 80

# Port range
checkmy port example.com -p 80-443

# Port list
checkmy port example.com -p 22,80,443,8080

# Mixed (range + list)
checkmy port example.com -p 22,80-82,443,8080-8443
```

### Port Presets

```bash
# Common ports (top 25) - default
checkmy port example.com -p common

# Web server ports
checkmy port example.com -p web

# Database ports
checkmy port example.com -p db

# Mail server ports
checkmy port example.com -p mail

# Well-known ports (1-1024)
checkmy port example.com -p full

# All ports (1-65535) - WARNING: slow!
checkmy port example.com -p all
```

### Filtering

By default, only open ports are shown. Use `--all` to include closed and filtered ports:

```bash
# Show all ports (open, closed, and filtered)
checkmy port example.com -p common --all

# Scan web ports, show all results
checkmy port example.com -p web --all
```

### Performance Tuning

```bash
# Custom timeout per port
checkmy port example.com -p full --timeout 2s

# Increase concurrency (faster but more aggressive)
checkmy port example.com -p full --concurrency 100

# Decrease concurrency (slower but gentler)
checkmy port example.com -p full --concurrency 10
```

### Output Options

```bash
# JSON output
checkmy port example.com -p web -j

# Disable colors
checkmy port example.com --no-color
```

### Interrupt Handling

```bash
# Press Ctrl+C during scan to show partial results
checkmy port example.com -p all
# ^C
# Shows results scanned so far with exit code 130
```

---

## JSON Output & jq Examples

All commands support `--json` / `-j` for machine-readable output.

### Smart Mode

```bash
# Get phase statuses
checkmy example.com -j | jq '{dns: .dns.status, whois: .whois.status, ports: .ports.status, tls: .tls.status, http: .http.status}'

# Check if all phases passed
checkmy example.com -j | jq '[.dns, .whois, .ports, .tls, .http | select(. != null) | .status] | all(. == "ok")'

# Get TLS certificate days left
checkmy example.com -j | jq '.tls.days_left'

# Get WHOIS expiration
checkmy example.com -j | jq '{expires: .whois.expires, days_left: .whois.days_left}'

# Get HTTP final URL after redirects
checkmy example.com -j | jq -r '.http.final_url'

# Get resolved IPs
checkmy example.com -j | jq '{a: .dns.a, aaaa: .dns.aaaa}'

# Get total audit time
checkmy example.com -j | jq '.total_time_ms'

# Quick mode (no WHOIS in output)
checkmy example.com --quick -j | jq 'keys'
```

### IP

```bash
# Get country and city
checkmy ip 8.8.8.8 -j | jq '{country: .country, city: .city}'

# Get ASN and organization
checkmy ip 1.1.1.1 -j | jq '{asn: .asn, org: .organization}'

# Get coordinates
checkmy ip 8.8.8.8 -j | jq '{lat: .latitude, lon: .longitude}'

# Get reverse DNS hostname
checkmy ip 8.8.8.8 -j | jq -r '.hostname'
```

### DNS

```bash
# Get all A record IPs
checkmy dns google.com -t A -j | jq -r '.answers[].data'

# Get TTL of first record
checkmy dns example.com -j | jq '.answers[0].ttl'

# List all record types found
checkmy dns example.com -j | jq -r '.answers[].record_type' | sort -u

# Get query time
checkmy dns example.com -j | jq '.query_time_ms'
```

### Trace

```bash
# Check if target was reached
checkmy trace example.com -r -j | jq '.reached_target'

# Get all hop IPs
sudo checkmy trace example.com -r -j | jq -r '.hops[].ip // "unknown"'

# Get average latency per hop
sudo checkmy trace example.com -r -j | jq '.hops[] | "\(.ttl): \(.avg_ms)ms"'

# Find hops with packet loss
sudo checkmy trace example.com -r -j | jq '.hops[] | select(.loss_percent > 0)'
```

### Certificate

```bash
# Get certificate expiration date
checkmy cert example.com -j | jq -r '.certificates[0].not_after'

# Get days until expiration
checkmy cert example.com -j | jq '.certificates[0].days_left'

# Get all SANs (Subject Alternative Names)
checkmy cert example.com -j | jq -r '.certificates[0].san[]'

# Get issuer organization
checkmy cert example.com -j | jq -r '.certificates[0].issuer.organization'
```

### WHOIS

```bash
# Get domain registrar
checkmy whois example.com -j | jq -r '.registrar'

# Get expiration date
checkmy whois example.com -j | jq -r '.expires'

# Get all name servers
checkmy whois example.com -j | jq -r '.name_servers[]'

# Get days until expiration
checkmy whois example.com -j | jq '.days_until_expiry'
```

### Connect

```bash
# Get TLS version
checkmy connect example.com 443 --tls -j | jq -r '.tls.protocol'

# Get cipher suite
checkmy connect example.com 443 --tls -j | jq -r '.tls.cipher'

# Get connection time
checkmy connect example.com 80 -j | jq '.connect_time_ms'

# Get response (if sent data)
checkmy connect example.com 80 --send "GET / HTTP/1.0\r\n\r\n" -j | jq -r '.response'
```

### HTTP

```bash
# Get status code
checkmy http example.com -j | jq '.response.status'

# Get response time
checkmy http example.com -j | jq '.timing.total_ms'

# Get all response headers
checkmy http example.com -j | jq '.response.headers'

# Get specific header
checkmy http example.com -j | jq -r '.response.headers[] | select(.[0] == "content-type") | .[1]'

# Check if healthcheck passed
checkmy http example.com -j | jq '.success'

# Get redirect chain
checkmy http http://example.com -j | jq '.redirects[].url'
```

### Port

```bash
# Get all open ports
checkmy port example.com -j | jq '.ports[] | select(.state == "open") | .port'

# Get open ports with service names
checkmy port example.com -j | jq -r '.ports[] | select(.state == "open") | "\(.port) - \(.service)"'

# Count open ports
checkmy port example.com -j | jq '.summary.open'

# Check if specific port is open
checkmy port example.com -p 443 -j | jq '.ports[0].state == "open"'

# Get scan time
checkmy port example.com -j | jq '.scan_time_ms'

# Check if scan was interrupted
checkmy port example.com -j | jq '.interrupted // false'
```

---

## Scripting Examples

### Full Audit Monitor

```bash
#!/bin/bash
# audit-monitor.sh - Run smart audit on multiple domains and report failures

DOMAINS=("example.com" "api.example.com" "staging.example.com")
FAILED=0

for domain in "${DOMAINS[@]}"; do
  result=$(checkmy "$domain" --quick -j 2>/dev/null)
  
  # Check each phase status
  for phase in dns ports tls http; do
    status=$(echo "$result" | jq -r ".$phase.status // empty")
    if [ "$status" = "fail" ]; then
      echo "[FAIL] $domain - $phase failed"
      FAILED=1
    elif [ "$status" = "warn" ]; then
      echo "[WARN] $domain - $phase warning"
    fi
  done
  
  # Check TLS certificate expiry
  tls_days=$(echo "$result" | jq '.tls.days_left // empty')
  if [ -n "$tls_days" ] && [ "$tls_days" -lt 30 ]; then
    echo "[WARN] $domain - certificate expires in $tls_days days"
  fi
done

exit $FAILED
```

### Health Check Script

```bash
#!/bin/bash
# health-check.sh - Check multiple services

SERVICES=(
  "https://api.example.com/health"
  "https://web.example.com"
  "https://auth.example.com/status"
)

for url in "${SERVICES[@]}"; do
  if checkmy http "$url" --match "ok" --timeout 5s > /dev/null 2>&1; then
    echo "[OK] $url"
  else
    echo "[FAIL] $url"
  fi
done
```

### Certificate Expiry Monitor

```bash
#!/bin/bash
# cert-monitor.sh - Alert on certificates expiring soon

DOMAINS=("example.com" "api.example.com" "www.example.com")
WARN_DAYS=30

for domain in "${DOMAINS[@]}"; do
  days=$(checkmy cert "$domain" -j | jq '.certificates[0].days_left')
  if [ "$days" -lt "$WARN_DAYS" ]; then
    echo "WARNING: $domain expires in $days days"
  else
    echo "OK: $domain ($days days left)"
  fi
done
```

### Port Scan Report

```bash
#!/bin/bash
# port-report.sh - Generate port scan report

TARGET=$1
checkmy port "$TARGET" -p common -j | jq -r '
  "Host: \(.target) (\(.resolved_ip))",
  "Scan Time: \(.scan_time_ms)ms",
  "",
  "Open Ports:",
  (.ports[] | select(.state == "open") | "  \(.port)/tcp - \(.service)"),
  "",
  "Summary: \(.summary.open) open, \(.summary.closed) closed, \(.summary.filtered) filtered"
'
```

### DNS Record Comparison

```bash
#!/bin/bash
# dns-compare.sh - Compare DNS records across servers

DOMAIN=$1
SERVERS=("8.8.8.8" "1.1.1.1" "9.9.9.9")

echo "Comparing A records for $DOMAIN"
echo "================================"

for server in "${SERVERS[@]}"; do
  echo -n "$server: "
  checkmy dns "$DOMAIN" -t A -s "$server" -j | jq -r '.answers[].data' | tr '\n' ' '
  echo
done
```

### Service Discovery

```bash
#!/bin/bash
# discover.sh - Discover services on a host

HOST=$1

echo "Scanning $HOST..."
echo

# Scan common ports (only open ports shown by default)
checkmy port "$HOST" -p common -j | jq -r '
  .ports[] | "Port \(.port): \(.service) (\(.latency_ms)ms)"
'
```

### Batch HTTP Check with Exit Codes

```bash
#!/bin/bash
# batch-http.sh - Check multiple URLs, exit 1 if any fail

URLS=(
  "https://example.com"
  "https://api.example.com/health"
)

FAILED=0

for url in "${URLS[@]}"; do
  if ! checkmy http "$url" -j > /dev/null 2>&1; then
    echo "FAILED: $url"
    FAILED=1
  fi
done

exit $FAILED
```

---

## Exit Codes

All commands return meaningful exit codes for scripting:

### Smart Mode (Domain Audit)

| Code | Meaning |
|------|---------|
| 0 | Audit completed (all phases ran) |
| 1 | DNS resolution failed (audit aborted) |

> Note: When smart mode detects an IP address or host:port, it delegates to `ip` or `connect` respectively, using their exit codes.

### General

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |

### http

| Code | Meaning |
|------|---------|
| 0 | Success (2xx/3xx) |
| 1 | Connection/DNS error |
| 2 | Timeout |
| 3 | Client error (4xx) |
| 4 | Server error (5xx) |
| 5 | Match validation failed |

### port

| Code | Meaning |
|------|---------|
| 0 | At least one port open |
| 1 | All ports closed/filtered |
| 2 | DNS resolution failed |
| 130 | Interrupted (Ctrl+C) |

### connect

| Code | Meaning |
|------|---------|
| 0 | Connection successful |
| 1 | DNS resolution failed |
| 2 | Timeout |
| 3 | Connection refused |
| 4 | TLS error |
| 5 | I/O error |