quickstart

AWL Plugin Quickstart

Commands

• awl <resource> <action> — Execute awl commands
• awl lookup — Perform DNS lookup with JSON output
• awl lookup-a — Lookup A records with JSON output
• awl lookup-aaaa — Lookup AAAA records with JSON output
• awl lookup-mx — Lookup MX records with JSON output
• awl lookup-txt — Lookup TXT records with JSON output
• awl lookup-ns — Lookup NS records with JSON output
• awl lookup-https — DNS over HTTPS lookup with JSON output
• awl lookup-tls — DNS over TLS lookup with JSON output
• awl lookup-quic — DNS over QUIC lookup with JSON output
• awl lookup-dnscrypt — DNSCrypt lookup with JSON output

Overview

AWL (a pointed tool for making small holes) is a command-line DNS lookup tool that supports DNS queries over UDP, TCP, TLS, HTTPS, DNSCrypt, and QUIC. It's designed as a drop-in replacement for dig with modern protocol support and JSON output. The supercli awl plugin provides convenient commands for DNS lookups with structured JSON output.

Installation

The awl binary must be installed on your system:

# Via Go
go install dns.froth.zone/awl@latest

# Via Homebrew
brew install SamTherapy/tap/awl

# Via Alpine Linux
apk add awl-dns

# Via Arch Linux (AUR)
yay -S awl-dns-git

# Via Debian/Ubuntu
apt install awl-dns

Available Commands

Basic DNS Lookup

sc awl lookup example.com

Performs a standard DNS lookup and returns results in JSON format.

Record Type Specific Lookups

# A records (IPv4 addresses)
sc awl lookup-a example.com

# AAAA records (IPv6 addresses)
sc awl lookup-aaaa example.com

# MX records (mail servers)
sc awl lookup-mx example.com

# TXT records (text records)
sc awl lookup-txt example.com

# NS records (name servers)
sc awl lookup-ns example.com

Modern DNS Protocols

# DNS over HTTPS (DoH)
sc awl lookup-https example.com

# DNS over TLS (DoT)
sc awl lookup-tls example.com

# DNS over QUIC (DoQ)
sc awl lookup-quic example.com

# DNSCrypt
sc awl lookup-dnscrypt example.com

Protocol Support

AWL supports the following DNS protocols:

• UDP: Traditional DNS over UDP
• TCP: DNS over TCP
• TLS: DNS over TLS (DoT)
• HTTPS: DNS over HTTPS (DoH)
• DNSCrypt: Encrypted DNS protocol
• QUIC: DNS over QUIC (DoQ)

Output Format

All commands return structured JSON output, making it easy to parse and process in scripts:

{
  "response": {
    "answers": [
      {
        "name": "example.com",
        "type": "A",
        "class": "IN",
        "ttl": 300,
        "address": "93.184.216.34"
      }
    ]
  }
}

Use Cases

• Network diagnostics: Check DNS resolution across different protocols
• Security testing: Verify encrypted DNS (DoT/DoH) functionality
• Performance testing: Compare DNS resolution times across protocols
• Monitoring scripts: Integrate DNS health checks with JSON parsing
• Privacy: Use encrypted DNS protocols to avoid DNS surveillance

Caveats & Pitfalls

• Protocol availability: Not all DNS servers support modern protocols (DoH/DoT/DoQ)
• Network requirements: Encrypted protocols require specific server configurations
• JSON parsing: Output is always JSON; ensure your tools can parse JSON
• Server compatibility: Some DNS servers may not support all query types

Examples

Check domain resolution with DoH

sc awl lookup-https example.com

Verify DNS over TLS

sc awl lookup-tls example.com

Compare protocols

sc awl lookup example.com      # UDP
sc awl lookup-https example.com # DoH
sc awl lookup-tls example.com    # DoT

Query specific record type with DoH

sc awl lookup-a example.com
# Then manually add +https flag if needed

Test DNSCrypt

sc awl lookup-dnscrypt example.com

Use QUIC for DNS

sc awl lookup-quic example.com

Advantages Over Traditional Tools

• Modern protocols: Supports DoH, DoT, DoQ, and DNSCrypt
• JSON output: Structured output for programmatic use
• Drop-in replacement: Similar interface to dig
• Cross-platform: Written in Go for consistent behavior
• Privacy-focused: Encrypted DNS protocol support

Common Patterns

Verify encrypted DNS is working

sc awl lookup-https example.com | sc gojq query '.response.answers[].address'

Compare DNS resolution across protocols

for protocol in udp https tls quic; do
  echo "Testing $protocol:"
  sc awl lookup example.com +$protocol +json
done

Monitor DNS health

watch -n 60 'sc awl lookup example.com +json | sc gojq query ".response.answers[0]"'

Debug DNS resolution issues

sc awl lookup example.com +https +json | sc gojq query '.response'