CLI y herramientas para desarrolladores

Instalación

El CLI de NexDNS es un binario único sin dependencias externas. Elige el método de instalación que se adapte a tu entorno.

Script de instalación

curl -sL https://get.nexdns.tech/cli | sh

Detecta tu plataforma, descarga el archivo de la versión correspondiente, lo verifica con las sumas de comprobación publicadas junto a la versión e instala el binario en /usr/local/bin. Léelo antes con curl https://get.nexdns.tech/cli si prefieres no enviar a la shell un script sin revisar.

Instalar con Go

go install github.com/nexdns/cli/cmd/nexdns@latest

Homebrew

brew tap nexdns/tap
brew install --cask nexdns-cli

La fórmula se publica como cask, así que se instala con <code>--cask</code> en lugar de la forma de una sola línea <code>brew install</code>.

Descargar un archivo de la release

Los binarios precompilados para Linux, macOS y Windows (amd64 y arm64) se adjuntan a cada release en GitHub. Descomprime el archivo y coloca nexdns en cualquier directorio de tu PATH.

Docker

docker pull nexdns/cli

Verificar la instalación

Después de instalar, confirma que el CLI está disponible y verifica su versión:

nexdns version

Autenticación

El CLI requiere un token API para comunicarse con la API de NexDNS. Puedes crear un token en nexdns.tech/settings/api-keys.

Requisito de plan: el CLI funciona a través de la API REST, por lo que necesita una clave API, disponible en los planes Pro y superiores. Lo mismo aplica al proveedor Terraform, al proveedor OctoDNS y a los plugins ACME.

Guardar token en la configuración

nexdns auth token nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Variable de entorno (CI/CD)

export NEXDNS_TOKEN=nxd_xxxxxxxxxxxxxxxxxxxx

Verificar estado de autenticación

nexdns auth status

Archivo de configuración

El token se almacena en ~/.nexdns/config.yaml. El CLI resuelve las credenciales en el siguiente orden de prioridad:

1. Opción --token (prioridad más alta)
2. Variable de entorno NEXDNS_TOKEN
3. Archivo de configuración ~/.nexdns/config.yaml

Gestión de zonas

Gestiona zonas DNS desde la línea de comandos. Todos los comandos de zona están bajo el subcomando nexdns zone.

Listar zonas

El listado está paginado. Usa --all para recorrer todas las páginas, o --search, --page y --per-page para acotarlo.

nexdns zone list
nexdns zone list --all
nexdns zone list --search example --per-page 50

Añadir una zona

nexdns zone add example.com --ns-group eu

Para crear una zona secundaria que se transfiera desde tu propio primario, pasa --type slave con la dirección IP pública del primario. Las zonas secundarias están disponibles en los planes Pro y superiores.

nexdns zone add example.com --type slave --master-ip 203.0.113.10

Información de la zona

nexdns zone info example.com

Exportar una zona

Exporta la zona en formato de archivo de zona BIND, listo para redirigir a un archivo. Pasa --format json si prefieres un inventario legible por máquina.

nexdns zone export example.com > example.com.zone
nexdns zone export example.com --format json

Importar archivo de zona

Usa --dry-run para previsualizar los cambios antes de aplicarlos:

nexdns zone import example.com zone.txt --dry-run
nexdns zone import example.com zone.txt

Por defecto, una importación solo añade lo que falta. Añade --replace para eliminar también los registros que el archivo no define, de modo que la zona coincida exactamente con el archivo. Los registros NS y SOA propios de la zona nunca se modifican.

nexdns zone import example.com zone.txt --replace

Asegurar que la zona existe

Crea la zona solo si no existe aún (idempotente):

nexdns zone ensure example.com

Mover una zona a otro grupo de servidores de nombres

Mueve la zona a otro grupo de servidores de nombres, indicado por su slug. La zona sigue respondiendo en todo momento: los servidores de nombres del nuevo grupo se aprovisionan antes de que el comando termine y los antiguos siguen sirviendo mientras los resolvers se actualizan. Después, actualiza la delegación en tu registrador – nexdns zone info muestra los nuevos servidores de nombres.

nexdns zone move example.com eu --dry-run
nexdns zone move example.com eu

Una zona puede moverse tres veces al día. Superado ese límite, el comando lo indica y no cambia nada.

Comprobar la propagación DNS

Consulta directamente los resolvers públicos, no la API, así que ves lo que ve internet. Termina con un código distinto de cero cuando una comprobación falla, así que sirve como control bloqueante en un despliegue.

nexdns zone check example.com

Eliminar una zona

Pide confirmación antes de actuar. Añade --force para omitir la pregunta en un script; sin terminal, la confirmación se rechaza automáticamente y no se elimina nada.

nexdns zone delete example.com
nexdns zone delete example.com --force

Gestión de registros

Gestiona registros DNS dentro de una zona. Todos los comandos de registros están bajo el subcomando nexdns record.

Listar registros

Filtra con --type, --name (una etiqueta, o @ para el ápice de la zona) o --search, que busca en nombres y contenido.

nexdns record list example.com
nexdns record list example.com --type MX
nexdns record list example.com --name www
nexdns record list example.com --search 203.0.113

Añadir registros

El argumento content lleva solo el valor principal. Todo lo demás que necesita un tipo de registro – prioridad, peso, puerto, el tag y los flags de CAA, parámetros de DS y TLSA – es una opción aparte, así que no hay que ensamblar nada a mano.

# A record
nexdns record add example.com A www 1.2.3.4 --ttl 300

# MX record with priority
nexdns record add example.com MX @ mail.example.com --priority 10

# SRV: priority, weight and port are separate flags
nexdns record add example.com SRV _sip._tcp sip.example.com --priority 10 --weight 60 --port 5060

# CAA: the value is the CA domain, the rest are flags
nexdns record add example.com CAA @ letsencrypt.org --tag issue --flags 0

# DS and TLSA: content is the bare hex digest
nexdns record add example.com DS child 0123456789abcdef --keytag 12345 --algorithm 13 --digest-type 2
nexdns record add example.com TLSA _443._tcp.www 0123456789abcdef --usage 3 --selector 1 --matching-type 1

El TTL se aplica a todo el conjunto de registros. Omite --ttl al añadir otro valor a un nombre que ya existe y se conserva el TTL actual; si lo pasas, todos los valores de ese nombre pasan a ese TTL. Un nombre nuevo usa 3600 segundos por defecto.

Actualizar un registro

Cambia el contenido, el TTL, la prioridad o la etiqueta. Los ID de registro se derivan del propio registro, así que una edición devuelve un ID nuevo – léelo siempre de la respuesta en lugar de reutilizar el anterior.

nexdns record update example.com <record-id> --content 5.6.7.8
nexdns record update example.com <record-id> --ttl 600
nexdns record update example.com <record-id> --record-name api

Crear el registro si no existe

Crea el registro solo si aún no existe (una coincidencia exacta de tipo, nombre y contenido). Los registros existentes con contenido distinto no se modifican – seguro para configuraciones round-robin. Idempotente:

nexdns record ensure example.com A www 1.2.3.4

Eliminar un registro

nexdns record delete example.com <record-id>

DNSSEC

Gestiona la firma DNSSEC de tus zonas.

Verificar estado de DNSSEC

nexdns dnssec status example.com

Habilitar DNSSEC

nexdns dnssec enable example.com

Obtener registros DS

Recuperar registros DS para configurar en tu registrador de dominios:

nexdns dnssec ds-records example.com

Deshabilitar DNSSEC

Pide confirmación, ya que deshabilitar la firma en una zona delegada rompe la validación hasta que retires el registro DS en tu registrador. Añade --force en un script.

nexdns dnssec disable example.com --force

DNS como código

Define tu infraestructura DNS de forma declarativa en un archivo nexdns.yaml y gestiónala con control de versiones. El CLI compara tu configuración local con el estado en producción y aplica solo los cambios necesarios.

Formato de configuración

zones:
  example.com:
    dnssec: true
    records:
      - type: A
        name: "@"
        content: "1.2.3.4"
        ttl: 300
      - type: CNAME
        name: www
        content: example.com

Vista previa de cambios

Mostrar un diff de lo que cambiaría sin aplicar nada:

nexdns apply

Aplicar cambios

Aplicar los cambios después de revisar el diff:

nexdns apply --confirm

Solo diff

nexdns diff

Eliminar los registros que ya no están en el archivo

Un registro que borras de nexdns.yaml se mantiene a menos que pidas las eliminaciones de forma explícita. Es deliberado: evita que un archivo parcial vacíe una zona. Añade --delete para que el archivo sea la fuente autoritativa.

nexdns diff --delete
nexdns apply --confirm --delete

Elegir el archivo y la zona

Usa --file para una configuración fuera del directorio de trabajo y --zone para actuar sobre una sola zona de un archivo con varias. Un --zone que no nombre ninguna zona del archivo es un error, no una operación vacía silenciosa.

nexdns apply --file production.yaml --zone example.com --confirm

Obtener estado actual

Genera un archivo nexdns.yaml a partir de la configuración DNS actual en producción:

nexdns pull example.com
nexdns pull example.com --file nexdns.yaml
nexdns pull other.example --file nexdns.yaml --append

Sustitución de variables de entorno

Usa la sintaxis ${VARIABLE} en tu archivo de configuración. El CLI sustituye las variables de entorno en el momento de la aplicación, facilitando la reutilización de configuraciones entre entornos:

zones:
  ${DOMAIN}:
    records:
      - type: A
        name: "@"
        content: "${SERVER_IP}"

Webhooks

Suscribe un endpoint a los eventos que emiten tus zonas y gestiona esas suscripciones desde el terminal. Los webhooks están disponibles en los planes Pro y superiores; la clave API necesita los permisos webhooks.read y webhooks.write.

Suscribir un endpoint

El secreto de firma se muestra una sola vez, al crear la suscripción, y después no se puede recuperar – guárdalo donde tu receptor pueda leerlo. Cada entrega lleva una firma HMAC calculada con ese secreto, así que el receptor puede verificar que la solicitud viene realmente de nosotros.

nexdns webhook create https://example.com/hooks/dns \
    --events zone.created,zone.deleted,record.created \
    --description "production"

Eventos disponibles

zone.created, zone.updated, zone.deleted, record.created, record.updated, record.deleted, dnssec.enabled, dnssec.disabled, zone.health.problem, zone.health.resolved

Inspeccionar suscripciones

show añade los diez últimos intentos de entrega con su código de estado y, cuando alguno ha fallado, el error – suele bastar para distinguir una URL mal escrita de un receptor que rechaza la carga.

nexdns webhook list
nexdns webhook show <webhook-id>

Enviar un evento de prueba

Pone en cola una entrega de prueba. Un resultado correcto aquí significa que la plataforma aceptó el evento, no que tu endpoint respondiera – consulta el resultado con nexdns webhook show.

nexdns webhook test <webhook-id>

Cambiar o pausar una suscripción

Pasa solo lo que cambia; el comando lee la suscripción actual y reenvía el resto. Usa --active=false para detener las entregas sin eliminar el endpoint, y --force para eliminar sin pedir confirmación.

nexdns webhook update <webhook-id> --events zone.created,dnssec.enabled
nexdns webhook update <webhook-id> --active=false
nexdns webhook delete <webhook-id> --force

Cuenta y configuración

Consulta a qué cuenta pertenece un token, qué plan tiene asociado y qué claves API existen.

nexdns account info
nexdns account api-keys

Ajustes guardados

El archivo de configuración guarda cinco ajustes – api-url, token, output, color y timeout – y todos se pueden leer y escribir desde el CLI. config view muestra la configuración efectiva, incluido de dónde viene el token.

nexdns config view
nexdns config set output json
nexdns config set timeout 60
nexdns config get api-url

Variables de entorno

Cada ajuste tiene también una variable de entorno, que es lo que suelen usar los runners de CI. NEXDNS_CONFIG apunta a un archivo de configuración alternativo, útil cuando se manejan varias cuentas desde un mismo equipo.

export NEXDNS_TOKEN=nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export NEXDNS_API_URL=https://api.nexdns.tech/v1
export NEXDNS_TIMEOUT=60
export NEXDNS_CONFIG=/etc/nexdns/config.yaml

Quitar un token guardado

Borra el token del archivo de configuración. El archivo en sí, y cualquier URL de API guardada en él, se mantienen.

nexdns auth logout

Autocompletado del shell

Se generan scripts de autocompletado para bash, zsh, fish y PowerShell.

nexdns completion bash > /etc/bash_completion.d/nexdns
nexdns completion zsh > "${fpath[1]}/_nexdns"

Scripting y CI

El CLI está pensado para ejecutarse desde pipelines: cada fallo tiene su propio código de salida, las confirmaciones se rechazan en lugar de quedarse colgadas y nada destructivo ocurre sin pedirlo.

Códigos de salida

Un subcomando mal escrito termina con 2 en lugar de mostrar la ayuda y darse por bueno, así que una errata en un pipeline no puede pasar por una operación completada.

Peticiones de confirmación

Los comandos destructivos preguntan antes de actuar. Sin terminal – que es el caso de cualquier runner de CI – la confirmación se rechaza y el comando termina con 0 sin haber cambiado nada, así que pasa --force cuando de verdad quieras que actúe.

Fallos que antes pasaban desapercibidos

• Un ${VAR} sin resolver en nexdns.yaml detiene la ejecución y nombra todas las variables sin valor, en lugar de escribir el texto literal en un registro.
• Un --zone que no nombre ninguna zona del archivo es un error.
• zone check termina con un código distinto de cero cuando falla una comprobación de propagación.
• apply --confirm termina con un código distinto de cero cuando alguna operación ha fallado, e indica cuántas.

Límites de solicitudes y trabajos masivos

El cupo de la API es por cuenta y por plan, en una ventana deslizante de un minuto. El CLI lee el cupo en cada respuesta y espera a que la ventana se reinicie antes de superarlo, de modo que una importación grande termina íntegra en lugar de perder registros: simplemente tarda más. Un límite con una ventana más larga, como el tope de veces que una zona puede cambiar de grupo de servidores de nombres, se notifica en lugar de esperar a que se agote.

Docker

El CLI está disponible como imagen Docker. Pasa tu token API a través de la variable de entorno NEXDNS_TOKEN.

Ejecutar comandos

docker run --rm -e NEXDNS_TOKEN=nxd_xxx nexdns/cli zone list

Importar un archivo de zona

Monta un directorio local para pasar archivos de zona al contenedor:

docker run --rm -e NEXDNS_TOKEN=nxd_xxx \
    -v "$PWD/zones:/zones" \
    nexdns/cli zone import example.com /zones/example.com.zone

Opciones globales

Las siguientes opciones están disponibles en todos los comandos:

Cada una de ellas lee también una variable de entorno: NEXDNS_TOKEN, NEXDNS_API_URL, NEXDNS_TIMEOUT y NEXDNS_CONFIG. NO_COLOR desactiva el color independientemente de --color.

Terraform

El proveedor Terraform de NexDNS te permite gestionar zonas y registros como recursos de Terraform. Instala el proveedor desde el Terraform Registry y configúralo con tu token API.

terraform {
  required_providers {
    nexdns = {
      source = "nexdns/nexdns"
    }
  }
}

provider "nexdns" {
  api_token = var.nexdns_token
}

resource "nexdns_zone" "main" {
  name     = "example.com"
  ns_group = "eu"
}

resource "nexdns_record" "www" {
  zone_id = nexdns_zone.main.id
  type    = "A"
  name    = "www"
  content = "1.2.3.4"
}

Integración con DNSControl

DNSControl es una herramienta DNS-as-code de Stack Overflow. Usa el proveedor de NexDNS para gestionar tus zonas de forma declarativa. El proveedor se incluye en DNSControl a partir de la versión 4.46.0.

creds.json

{
    "nexdns": {
        "TYPE": "NEXDNS",
        "api_token": "nxd_xxxxxxxxxxxxxxxxxxxx"
    }
}

dnsconfig.js

var REG_NONE = NewRegistrar("none");
var DSP_NEXDNS = NewDnsProvider("nexdns");

D("example.com", REG_NONE, DnsProvider(DSP_NEXDNS),
    A("@", "1.2.3.4"),
    A("www", "1.2.3.4"),
    MX("@", 10, "mail.example.com."),
    CNAME("blog", "example.com.")
);

OctoDNS

OctoDNS es una herramienta DNS-as-code de GitHub. Instala el proveedor de NexDNS y configúralo como origen o destino en tu configuración de OctoDNS.

Instalar proveedor

pip install octodns-nexdns

Archivo config/production.yaml

providers:
  config:
    class: octodns.provider.yaml.YamlProvider
    directory: ./config
  nexdns:
    class: octodns_nexdns.NexdnsProvider
    token: env/NEXDNS_API_TOKEN

zones:
  example.com.:
    sources:
      - config
    targets:
      - nexdns

Archivo zones/example.com.yaml

"":
  type: A
  value: 1.2.3.4
www:
  type: A
  value: 1.2.3.4
blog:
  type: CNAME
  value: example.com.