Skip to content

Route53 CLI - Get info about your records from the terminal - quickly!


Notifications You must be signed in to change notification settings


Folders and files

Last commit message
Last commit date

Latest commit



81 Commits

Repository files navigation

Route53 Query


Visit surf cli repo.

image info

Move fast with custom CLI for Route53.

Get info about your Route53 records from the Command line - quickly!

  • Direct link to resource on AWS Console.
  • Automatic verification of Nameservers against the real world.
  • Recursive search for all results via -R flag.
  • Supports any ~/.aws/credentials profile.
  • Works directly against AWS API.

The Problem

Ever wondered "what records are behind this R53 record I have?"

i.e Where does points to in R53?

Without route53-cli:

Go to browser -> AWS console -> login -> Route53 -> find the hosted zone -> find the record

Even if you find the record in the AWS console you can't be sure this is the source of truth since the record could be defined in multiple route 53 hosted zones of the organization. The only way to verify is by comparing the Nameservers in the real world.

The solution

  • The CLI will use the default AWS login methods and query the Route53 API in a smart way to find the record.
  • By default the nameservers will be verified against the real world via Dig implementation (turn off via --skip-ns).
  • Search recursivly and expand all the records until the "leaf".
  • Direct Web URL to the resource from the terminal.
  • SDK support for programatic access and JSON output.

With route53-cli:


r53 -r ''


│ HOSTED ZONE     │ ID                         │ TOTAL RECORDS │ PRIVATE │
│    │ /hostedzone/ABFDCEWQSFDSFD │           127 │ false   │

| # | Record                | Target                 | Console Link                         | TYPE    |
| 1 | * |     |                                      | A       |
| 2 | * |     |                                      | A       |
| 3 |    |  | | A       |
| 4 |    |  | | A       |

Programatic Access

Use the output with another program:

r53 -r '' --output-json --output-file output.json

Use the code in SDK mode (another go project):

package main

import (


func main() {
	input, _ := sdk.NewInput("", "my-aws-conf-profile", false, false, false, true, 3)
	result, _ := sdk.SearchR53(input)
	jsonOut, _ := sdk.ToJSONOutput(result, true)



MacOS (and ubuntu supported) installation via Brew:

brew tap isan-rivkin/toolbox
brew install r53

Download Binary

  1. from releases

  2. Move the binary to global dir and change name to r53:

cd <downloaded zip dir>
mv r53 /usr/local/bin

Install from Source

git clone 
cd route53-cli
make install BIN_DIR='/path/to/target/bin/dir'

Version Check

The CLI will query anonymously a remote version server to check if the current version of the CLI is updated. If the current client version indeed outdated the server will return instructions for update.

The server will add the request to a hit counter stored internaly for usage metrics.

None of the user query are passed to the server, only OS type and version.

The route53 querys themselves are done directly via the AWS Api.

This behaviour is on by default and can be optouted out via setting the envrionment variable R53_VERSION_CHECK=false.

How it works

Example pseudocode:

# i.e
# into 
record = '*.<a>.<b><c>.<d>'
record = strip_non_domain(record)
record = split(record)
hasWildCard = record[0] == '*'
len == record.length
# a 
if len == 1 and not hasWildCard: 
# *.a
if len == 2 and hasWildCard:  
# a.b
if len == 2 and not hasWildCard:  
# *.a.b
if len == 3 and hasWildCard: 
# a.b.c
if len == 3 and hasWildCard: 
    if not lookup(2)
# *.a.b.c.d.e
if len > 3:
    for chunksNum in (2, len):
        if (chunksNum == len and hasWildCard):
            return None
        if res = lookup(chunksNum)
            return res 

def lookup(dnsChunk):
    zoneIds = getZoneIds(dnsChunk)
    for zoneId in zoneIds:
        if zoneId name == dnsChunk: 
            aliasTargets = getAliasTargets(record, zoneId)
            return aliasTargetes