Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build Status Maintainability Test Coverage

A command-line utility to manipulate DNS records


Grab the latest binary from the releases page and drop it in your $PATH.


A username and API key to the API are required.

Getting an API key

You can get an API key by going to and filling out the form. Support will later email you two keys; you will want to use the "production" key. namedns does not do anything besides manipulate DNS records on domains you already own, so under Which best describes you? just pick I am looking to manage domains via an API. The process usually takes one or two business days.

Required global flags

Key Flag Description
username -u, --username username
api-key -k, --api-key production API key

Optional global flags

Key Flag Description Default value
api-url --api-url base API URL goname.NameAPIBaseURL
--config Path to a configuration file see list below
output -o, --output Output format: json, table, or yaml table
verbose -v, --verbose Display debugging output false


You can save keys to a configuration file so you don't have to specify your username or API key as part of the command. It may be in any format viper recognizes (JSON, TOML, YAML, etc.).

username: username
api-key: xxxxx.yyyyy.zzzzz

The configuration may be stored in one of these locations, and are searched in the following order:

  • $XDG_CONFIG_HOME/namedns/.namedns.yaml.
  • $XDG_CONFIG_DIRS/namedns/.namedns.yaml.
  • $HOME/.namedns.yaml.
  • .namedns.yaml

You may also use environment variables to replace flags; uppercased and prefixed by NAMEDNS_.

NAMEDNS_USERNAME=username NAMEDNS_API_KEY=xxxxx.yyyyy.zzzzz namedns list


Command Arguments Description
create <domain> <host> <type> <content> [--ttl] Create a DNS record in a domain
delete <domain> <record id> [record id ...] Delete one or more DNS records from a domain
list [domain ...] List all DNS records for one or more domains
help Display help and exit
version Display version and exit

You may optionally specify a --ttl flag (time to live, in seconds) for the create and set commands. If unspecified, records will be created with a default TTL of 3600 (1 hour). You can set it to as low as 60 according to the API spec, but the production API does not currently appear to accept a TTL lower than 300.



# create an A record for with the value ""
$ namedns create www a ""
INFO[0000] record created successfully    content= createDate="2017-01-01 12:00:00" priority=0 recordID=1234 ttl=3600 type=A

# create a TXT record for with the value "hello world!" and a TTL of 300 seconds
$ namedns create www txt "hello world!" --ttl 300
INFO[0000] record created successfully    content="hello world!" createDate="2017-01-01 12:00:00" priority=0 recordID=1235 ttl=300 type=TXT

# list all DNS records for a domain on an account
$ namedns list
1234 A 3600
1235 TXT hello world! 300

# delete record ID 1234 from
$ namedns delete 1234
INFO[0000] record deleted successfully    recordID=1234

Usage for dehydrated hooks (for Let's Encrypt)

Drop namedns into your $PATH and these two functions into

deploy_challenge() {
  local DOMAIN="${1}" TOKEN_FILENAME="${2}" TOKEN_VALUE="${3}"

  SUB_DOMAIN="_acme-challenge.$(sed -E 's/(.*)\.(\w+\.\w+)\.?$/\1/' <<< "$DOMAIN")"
  ROOT_DOMAIN="$(sed -E 's/(.*)\.(\w+\.\w+)\.?$/\2/' <<< "$DOMAIN")"
  [ "$DOMAIN" == "$ROOT_DOMAIN" ] && SUB_DOMAIN='_acme-challenge'

  namedns create "$ROOT_DOMAIN" "$SUB_DOMAIN" txt "$TOKEN_VALUE" --ttl 300 && sleep 90

clean_challenge() {
  local DOMAIN="${1}" TOKEN_FILENAME="${2}" TOKEN_VALUE="${3}"

  ROOT_DOMAIN="$(sed -E 's/(.*)\.(\w+\.\w+)\.?$/\2/' <<< "$DOMAIN")"

  record_id=$(namedns list "$ROOT_DOMAIN" | grep "$TOKEN_VALUE" | awk '{print $1}')
  namedns delete "$ROOT_DOMAIN" "$record_id"


dep ensure
go build -ldflags "-X '$(git describe --tags --candidates=1 --dirty --abbrev=40)'"



A command-line utility to manipulate DNS records







No packages published