Scroll to navigation

CLI53(1) User Commands CLI53(1)

NAME

cli53 - command line tool for Amazon Route 53 DNS management

SYNOPSIS

cli53 [global options] command [command options] [arguments...]

DESCRIPTION

cli53 is a command line interface for managing DNS zones and records on Amazon Route 53. It is aimed at system administrators, DevOps engineers and developers who prefer scriptable, automation-friendly workflows over the AWS web console.

The tool uses the BIND zone file format as its native interchange format, making it straightforward to migrate existing DNS configurations to Route 53 or to keep local backups of hosted zones under version control.

Main features:

•
Import and export hosted zones in standard BIND format.
•
Create, list and delete hosted zones.
•
Create, update and delete individual resource records.
•
Support for AWS-specific record types: weighted, latency-based, geolocation, failover and ALIAS records.
•
Create, list and delete reusable delegation sets.
•
Support for VPC-associated private hosted zones.
•
Authentication via ~/.aws/credentials, environment variables or IAM instance roles.

COMMANDS

List all hosted zones in the account. Supports multiple output formats via --format (text, json).
Create a new hosted zone. Accepts an optional --comment and --delegation-set-id to associate a reusable delegation set. Use --vpc-id and --vpc-region to create a private zone.
Delete a hosted zone by domain name or zone ID.
Validate the syntax of a BIND zone file without making any changes to Route 53. Useful to check zone files before importing.
Import a BIND zone file into a hosted zone. Supports dry-run mode, replace (full sync) and upsert (add or update without deleting).
Export a hosted zone as a BIND zone file to standard output. Use --full to emit fully-qualified domain names.
Create one or more resource records. Records are specified as quoted BIND-format strings. Supports weighted, latency, geolocation, failover, multivalue and ALIAS routing policies via flags.
Delete a specific resource record by name and type.
Delete all resource records in a zone except the SOA and the apex NS records. Use with caution.
Dynamically register EC2 instance names as DNS records by querying the EC2 API, keeping the zone in sync with running instances.
List all reusable delegation sets in the account.
Create a new reusable delegation set. Optionally takes a caller-reference.
Delete a reusable delegation set by its ID.
Show the list of commands or help for a specific command.

GLOBAL OPTIONS

Use a named profile from ~/.aws/credentials. Equivalent to setting AWS_PROFILE.
Assume the specified IAM role before making API calls. Can be combined with --profile.
Override the Route 53 endpoint. Accepts a hostname or a fully qualified URL. Useful for local testing (e.g. LocalStack).
Show help.
Print the version.

AUTHENTICATION

cli53 uses the standard AWS credential chain. Credentials are resolved in the following order:

1.
The file ~/.aws/credentials under the [default] profile or the profile named by --profile / AWS_PROFILE.
2.
The environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (and optionally AWS_SESSION_TOKEN).
3.
An IAM instance role attached to the EC2 instance (or ECS task) running the tool.

PRIVATE AND PUBLIC ZONES

When a domain has both a private and a public hosted zone, the domain name is ambiguous. In that case, pass the 13-character zone ID (shown after /hostedzone/ in the output of cli53 list) instead of the domain name:

cli53 rrcreate ZZZZZZZZZZZZZ 'name A 127.0.0.1'

EXAMPLES

Hosted zone management

List all hosted zones:

cli53 list

List zones in JSON format (useful with jq):

cli53 list --format json | jq '.[].Name'

Create a new hosted zone with a comment:

cli53 create --comment 'production zone' example.com

Create a private zone associated with a VPC:

cli53 create --vpc-id vpc-12345678 --vpc-region us-east-1 example.internal

Delete a hosted zone:

cli53 delete example.com

Importing and exporting zone files

Validate a zone file before importing:

cli53 validate --file zonefile.txt

Import a BIND zone file:

cli53 import --file zonefile.txt example.com

Dry-run import to preview changes without applying them:

cli53 import --file zonefile.txt --replace --dry-run example.com

Full replace (sync) waiting for completion:

cli53 import --file zonefile.txt --replace --wait example.com

Upsert: add new records and update existing ones without deleting:

cli53 import --file zonefile.txt --upsert example.com

Export a zone to stdout in BIND format:

cli53 export example.com

Export fully-qualified names, redirecting AWS debug output to a log file:

cli53 export --full --debug example.com > zone.txt 2> debug.log

Creating and managing resource records

Create an A record with TTL of 60 seconds:

cli53 rrcreate example.com 'www 60 A 192.168.0.1'

Update (replace) an existing A record:

cli53 rrcreate --replace example.com 'www 60 A 192.168.0.2'

Delete an A record:

cli53 rrdelete example.com www A

Create MX records:

cli53 rrcreate example.com '@ MX 10 mail1.' '@ MX 20 mail2.'

Create a round-robin A record (multiple values):

cli53 rrcreate example.com '@ A 192.168.0.1' '@ A 192.168.0.2'

Create CNAME records (relative and absolute):

cli53 rrcreate example.com 'login CNAME www'
cli53 rrcreate example.com 'mail CNAME ghs.googlehosted.com.'

Delete all records in a zone (dangerous):

cli53 rrpurge --confirm example.com

AWS routing policies

Create weighted records:

cli53 rrcreate --identifier server1 --weight 10 example.com 'www A 192.168.0.1'
cli53 rrcreate --identifier server2 --weight 20 example.com 'www A 192.168.0.2'

Create geolocation records (continent and subdivision):

cli53 rrcreate -i Africa --continent-code AF example.com 'geo 300 IN A 10.0.0.1'
cli53 rrcreate -i California --country-code US --subdivision-code CA     example.com 'geo 300 IN A 10.0.0.2'

Create primary/secondary failover records with a health check:

cli53 rrcreate -i Primary --failover PRIMARY     --health-check 2e668584-4352-4890-8ffe-6d3644702a1b     example.com 'ha 300 IN A 10.0.0.1'
cli53 rrcreate -i Secondary --failover SECONDARY     example.com 'ha 300 IN A 10.0.0.2'

Create multivalue answer records with health checks:

cli53 rrcreate -i One --multivalue     --health-check 2e668584-4352-4890-8ffe-6d3644702a1b     example.com 'ha 300 IN A 10.0.0.1'
cli53 rrcreate -i Two --multivalue     --health-check 7c90445d-ad67-47bd-9649-3ca0985e1f88     example.com 'ha 300 IN A 10.0.0.2'

ALIAS records

Create an ALIAS pointing to an ELB:

cli53 rrcreate example.com     'www AWS ALIAS A dns-name.elb.amazonaws.com. ABCDEFABCDE false'

Create an ALIAS pointing to another record in the same zone:

cli53 rrcreate example.com 'www AWS ALIAS A server1 $self false'

EC2 instances

Register all running EC2 instances as A records in the zone, using each instance Name tag as the hostname (requires EC2 read permissions):

cli53 instances example.com

Dry-run to preview the records that would be created:

cli53 instances --dry-run example.com

Use a specific AWS profile and region:

cli53 instances --profile production example.com

Reusable delegation sets

Create, list and delete a reusable delegation set:

cli53 dscreate
cli53 dslist
cli53 dsdelete NA24DEGBDGB32

Create a hosted zone using an existing delegation set:

cli53 create --delegation-set-id NA24DEGBDGB32 example.com

Profile and role switching

Use a non-default credentials profile:

cli53 list --profile staging

Assume an IAM role:

cli53 list --role-arn arn:aws:iam::123456789012:role/dns-manager

Combine profile and role:

cli53 list --profile staging     --role-arn arn:aws:iam::123456789012:role/dns-manager

CAVEATS

Amazon Route 53 limits change requests to a maximum of 100 resource record changes per API call. When an operation exceeds this limit, cli53 automatically splits it into multiple requests. A replace-style import involves deletes followed by creates, which may briefly leave the zone in an inconsistent state.

ENVIRONMENT

AWS access key ID.
AWS secret access key.
AWS session token (required when using temporary credentials).
Name of the profile to use from ~/.aws/credentials.
AWS region. Route 53 is a global service but some operations (e.g. VPC association) require a region to be set.

FILES

~/.aws/credentials
AWS credentials file. See aws-config(5) for the format.
~/.aws/config
AWS configuration file for region and output format defaults.

SEE ALSO

aws(1), bind(8), named-checkzone(8)

Amazon Route 53 documentation: https://docs.aws.amazon.com/route53/

Upstream source: https://github.com/barnybug/cli53

AUTHOR

Barnaby Gray <barnaby@pickle.me.uk>

This manual page was written by Josenilson Ferreira da Silva <nilsonfsilva@hotmail.com> for the Debian project.

2026-06 cli53 0.9.0