dnsx

A dependency-free & minimal DNS client. For the CLI, JavaScript & TypeScript.

Features

• Simple, lightweight DNS client
• Query any DNS record type (A, AAAA, MX, TXT, etc.)
• Multiple transport protocols (UDP, TCP, TLS, HTTPS)
• Colorized output with optional JSON format
• CLI and Library Support
• Zero runtime dependencies

Install

bun install -d @stacksjs/dnsx

Get Started

There are two ways of using this DNS client: as a library or as a CLI.

Library

Given the npm package is installed:

import { DnsClient } from '@stacksjs/dnsx'

// Simple query
const client = new DnsClient({
  domains: ['example.com'],
  type: 'A',
  nameserver: '1.1.1.1'
})

const responses = await client.query()
console.log(responses)

// Advanced configuration
const client = new DnsClient({
  domains: ['example.com'],
  type: ['A', 'MX', 'TXT'],
  nameserver: '1.1.1.1',
  udp: true, // use UDP transport
  edns: 'show', // show EDNS records
  txid: 1234, // set specific transaction ID
  tweaks: ['aa', 'bufsize=4096'] // protocol tweaks
})

const responses = await client.query()

CLI

# Simple queries
dnsx example.com                    # Query A record
dnsx example.com MX                 # Query MX record
dnsx example.com MX @1.1.1.1        # Use specific nameserver
dnsx example.com MX @1.1.1.1 -T     # Use TCP transport

# Advanced usage
dnsx -q example.com -t MX -n 1.1.1.1 --edns show   # Show EDNS records
dnsx example.com -J                                # JSON output
dnsx example.com --short                           # Short output format
dnsx example.com -Z bufsize=4096                   # Set UDP buffer size

Configuration

The DNS client can be configured using CLI options or through the library interface:

// dnsx.config.ts
import type { DnsOptions } from '@stacksjs/dnsx'

const config: DnsOptions = {
  // Query options
  query: 'example.com', // Domain to query
  type: 'A', // Record type (A, AAAA, MX, etc)
  nameserver: '1.1.1.1', // Nameserver to query
  class: 'IN', // Query class (IN, CH, HS)

  // Protocol options
  edns: 'show', // EDNS mode (disable, hide, show)
  txid: 1234, // Transaction ID
  Z: ['aa', 'bufsize=4096'], // Protocol tweaks

  // Transport options
  udp: true, // Use UDP transport
  tcp: false, // Use TCP transport
  tls: false, // Use DNS-over-TLS
  https: false, // Use DNS-over-HTTPS

  // Output options
  short: false, // Short output format
  json: false, // JSON output format
  color: 'auto', // Color output (always, auto, never)
  seconds: false, // Show raw seconds
  time: false // Show query time
}

export default config

And all CLI options map directly to these configuration options:

Usage:
  $ dnsx [...args]

Commands:
  [...args]  Perform DNS lookup for specified domains
  version    Show the version of dtsx

For more info, run any command with the `--help` flag:
  $ dnsx --help
  $ dnsx version --help

Options:
  -q, --query <HOST>       Host name or domain name to query
  -t, --type <TYPE>        Type of the DNS record being queried (A, MX, NS...)
  -n, --nameserver <ADDR>  Address of the nameserver to send packets to
  --class <CLASS>          Network class of DNS record (IN, CH, HS)
  --edns <SETTING>         Whether to OPT in to EDNS (disable, hide, show)
  --txid <NUMBER>          Set transaction ID to specific value
  -Z <TWEAKS>              Set uncommon protocol tweaks
  -U, --udp                Use DNS over UDP (default: false)
  -T, --tcp                Use DNS over TCP (default: false)
  -S, --tls                Use DNS-over-TLS (default: false)
  -H, --https              Use DNS-over-HTTPS (default: false)
  -1, --short              Display nothing but first result (default: false)
  -J, --json               Display output as JSON (default: false)
  --color <WHEN>           When to colorize output (always, auto, never)
  --seconds                Display durations in seconds (default: false)
  --time                   Print response time (default: false)
  --verbose                Print additional debugging information (default: false)
  -h, --help               Display this message
  -v, --version            Display version number

Examples:
dnsx example.com
dnsx example.com MX
dnsx example.com A AAAA NS MX
dnsx example.com -t MX -n 1.1.1.1 -T

Then run:

./dnsx start

To learn more, head over to the documentation.

Testing

bun test

Changelog

Please see our releases page for more information on what has changed recently.

Contributing

Please review the Contributing Guide for details.

Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

Postcardware

Two things are true: Stacks OSS will always stay open-source, and we do love to receive postcards from wherever Stacks is used! 🌍 We also publish them on our website. And thank you, Spatie

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

Credits

• dig
• dog
• Chris Breuer
• All Contributors

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙