CLI & Entwickler-Tools

Installationsanleitung

Das NexDNS CLI ist eine einzelne Binärdatei ohne externe Abhängigkeiten. Wählen Sie die Installationsmethode, die zu Ihrer Umgebung passt.

Installationsskript

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

Erkennt Ihre Plattform, lädt das passende Release-Archiv, prüft es gegen die mit dem Release veröffentlichten Prüfsummen und installiert die Binärdatei nach /usr/local/bin. Mit curl https://get.nexdns.tech/cli lesen Sie es vorher, wenn Sie ein ungelesenes Skript nicht an eine Shell weiterreichen möchten.

Mit Go installieren

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

Homebrew

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

Die Formel wird als Cask veröffentlicht und daher mit <code>--cask</code> installiert, nicht mit der einzeiligen <code>brew install</code>-Form.

Release-Archiv herunterladen

Vorkompilierte Binaries für Linux, macOS und Windows (amd64 und arm64) liegen jedem Release auf GitHub bei. Entpacken Sie das Archiv und legen Sie nexdns in ein Verzeichnis Ihres PATH.

Docker

docker pull nexdns/cli

Installation überprüfen

Bestätigen Sie nach der Installation, dass das CLI verfügbar ist, und prüfen Sie die Version:

nexdns version

Authentifizierung

Das CLI benötigt ein API-Token zur Kommunikation mit der NexDNS API. Sie können ein Token unter nexdns.tech/settings/api-keys erstellen.

Tarifanforderung: Das CLI arbeitet über die REST API und benötigt daher einen API-Schlüssel, der ab dem Pro-Tarif verfügbar ist. Dasselbe gilt für den Terraform-Provider, den OctoDNS-Provider und die ACME-Plugins.

Token in Konfiguration speichern

nexdns auth token nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Umgebungsvariable (CI/CD)

export NEXDNS_TOKEN=nxd_xxxxxxxxxxxxxxxxxxxx

Authentifizierungsstatus prüfen

nexdns auth status

Konfigurationsdatei

Das Token wird in ~/.nexdns/config.yaml gespeichert. Das CLI löst Anmeldedaten in der folgenden Prioritätsreihenfolge auf:

1. --token-Flag (höchste Priorität)
2. Umgebungsvariable NEXDNS_TOKEN
3. Konfigurationsdatei ~/.nexdns/config.yaml

Zonenverwaltung

Verwalten Sie DNS-Zonen über die Kommandozeile. Alle Zonenbefehle befinden sich unter dem Unterbefehl nexdns zone.

Zonen auflisten

Die Liste ist paginiert. Verwenden Sie --all, um alle Seiten zu durchlaufen, oder --search, --page und --per-page, um sie einzugrenzen.

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

Zone hinzufügen

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

Für eine sekundäre Zone, die die Daten von Ihrem eigenen Primary-Nameserver überträgt, übergeben Sie --type slave zusammen mit dessen öffentlicher IP-Adresse. Sekundäre Zonen sind ab dem Pro-Tarif verfügbar.

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

Zoneninformationen

nexdns zone info example.com

Zone exportieren

Exportiert die Zone im BIND-Zonendateiformat, direkt zum Umleiten in eine Datei. Mit --format json erhalten Sie stattdessen eine maschinenlesbare Bestandsliste.

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

Zonendatei importieren

Verwenden Sie --dry-run, um Änderungen vor der Anwendung in der Vorschau zu sehen:

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

Standardmäßig fügt ein Import nur hinzu, was fehlt. Mit --replace werden zusätzlich Einträge gelöscht, die die Datei nicht definiert – die Zone entspricht danach genau der Datei. Die eigenen Nameserver- und SOA-Einträge der Zone bleiben immer unangetastet.

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

Zonenexistenz sicherstellen

Erstellt die Zone nur, wenn sie noch nicht existiert (idempotent):

nexdns zone ensure example.com

Zone in eine andere Nameserver-Gruppe verschieben

Verschiebt die Zone in eine andere Nameserver-Gruppe, benannt über ihren Slug. Die Zone antwortet durchgehend weiter: Die Nameserver der neuen Gruppe werden bereitgestellt, bevor der Befehl zurückkehrt, und die alten beantworten Anfragen weiter, während die Resolver aktualisieren. Passen Sie danach die Delegierung bei Ihrem Registrar an – nexdns zone info gibt die neuen Nameserver aus.

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

Eine Zone darf dreimal pro Tag verschoben werden. Danach nennt der Befehl das Limit und ändert nichts.

DNS-Propagierung prüfen

Fragt öffentliche Resolver direkt ab, nicht die API – Sie sehen also, was das Internet sieht. Bei einer fehlgeschlagenen Prüfung endet der Befehl mit einem Exit-Code ungleich null und lässt sich damit als Freigabeprüfung in einer Deployment-Pipeline einsetzen.

nexdns zone check example.com

Zone löschen

Fragt zuerst nach einer Bestätigung. Mit --force überspringen Sie die Rückfrage in einem Skript; ohne Terminal wird die Rückfrage automatisch abgelehnt und nichts gelöscht.

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

Eintragsverwaltung

Verwalten Sie DNS-Einträge innerhalb einer Zone. Alle Eintragsbefehle befinden sich unter dem Unterbefehl nexdns record.

Einträge auflisten

Filtern Sie mit --type, --name (ein Label oder @ für den Zonenapex) oder --search, das Namen und Inhalt durchsucht.

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

Einträge hinzufügen

Das Argument content enthält nur den Primärwert. Alles Weitere, was ein Eintragstyp braucht – Priorität, Gewicht, Port, CAA-Tag und -Flags, DS- und TLSA-Parameter –, ist ein eigenes Flag; nichts muss von Hand zusammengesetzt werden.

# 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

Die TTL gilt für den gesamten Eintragssatz. Lassen Sie --ttl weg, wenn Sie einem bereits vorhandenen Namen einen weiteren Wert hinzufügen – die bestehende TTL bleibt dann erhalten; geben Sie sie an, wird die TTL für jeden Wert unter diesem Namen neu gesetzt. Bei einem völlig neuen Namen gilt der Standard von 3600 Sekunden.

Eintrag aktualisieren

Ändern Sie Inhalt, TTL, Priorität oder Label. Eintrags-IDs werden aus dem Eintrag selbst abgeleitet, deshalb liefert eine Änderung eine neue ID – lesen Sie sie immer aus der Antwort zurück und verwenden Sie nicht die alte weiter.

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

Eintrag bei Fehlen anlegen

Legt den Eintrag nur an, wenn er noch nicht existiert (exakte Übereinstimmung von Typ, Name und Inhalt). Bestehende Einträge mit abweichendem Inhalt bleiben unangetastet – sicher für Round-Robin-Setups. Idempotent:

nexdns record ensure example.com A www 1.2.3.4

Eintrag löschen

nexdns record delete example.com <record-id>

DNSSEC

Verwalten Sie die DNSSEC-Signierung für Ihre Zonen.

DNSSEC-Status prüfen

nexdns dnssec status example.com

DNSSEC aktivieren

nexdns dnssec enable example.com

DS-Einträge abrufen

DS-Einträge abrufen, um sie bei Ihrem Domain-Registrar zu konfigurieren:

nexdns dnssec ds-records example.com

DNSSEC deaktivieren

Fragt nach einer Bestätigung, denn wird die Signierung einer delegierten Zone abgeschaltet, schlägt die Validierung fehl, bis der DS-Eintrag bei Ihrem Registrar zurückgezogen ist. In einem Skript ergänzen Sie --force.

nexdns dnssec disable example.com --force

DNS als Code

Definieren Sie Ihre DNS-Infrastruktur deklarativ in einer nexdns.yaml-Datei und verwalten Sie sie mit Versionskontrolle. Das CLI vergleicht Ihre lokale Konfiguration mit dem Live-Zustand und wendet nur die notwendigen Änderungen an.

Konfigurationsformat

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

Änderungen vorschauen

Zeigt einen Diff der Änderungen an, ohne etwas anzuwenden:

nexdns apply

Änderungen anwenden

Wenden Sie die Änderungen nach der Überprüfung des Diffs an:

nexdns apply --confirm

Nur Diff

nexdns diff

Einträge entfernen, die nicht mehr in der Datei stehen

Ein Eintrag, den Sie aus nexdns.yaml löschen, bleibt bestehen, solange Sie Löschungen nicht ausdrücklich anfordern. Das ist Absicht: So leert eine unvollständige Datei keine Zone. Mit --delete wird die Datei maßgeblich.

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

Datei und Zone auswählen

Verwenden Sie --file für eine Konfiguration außerhalb des Arbeitsverzeichnisses und --zone, um aus einer Datei mit mehreren Zonen nur eine zu bearbeiten. Ein --zone, das keine Zone in der Datei benennt, ist ein Fehler und keine stille Nulloperation.

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

Live-Zustand abrufen

Generieren Sie eine nexdns.yaml aus der aktuellen Live-DNS-Konfiguration:

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

Umgebungsvariablen-Substitution

Verwenden Sie die Syntax ${VARIABLE} in Ihrer Konfigurationsdatei. Das CLI ersetzt Umgebungsvariablen zum Zeitpunkt der Anwendung, sodass Konfigurationen einfach über verschiedene Umgebungen hinweg wiederverwendet werden können:

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

Webhooks

Abonnieren Sie mit einem Endpunkt die Ereignisse, die Ihre Zonen aussenden, und verwalten Sie diese Abonnements im Terminal. Webhooks sind ab dem Pro-Tarif verfügbar; der API-Schlüssel benötigt die Berechtigungen webhooks.read und webhooks.write.

Endpunkt abonnieren

Das Signatur-Secret wird ein einziges Mal bei der Erstellung ausgegeben und ist danach nicht mehr abrufbar – hinterlegen Sie es dort, wo Ihr Empfänger es lesen kann. Jede Zustellung trägt eine mit diesem Secret berechnete HMAC-Signatur, sodass der Empfänger prüfen kann, ob die Anfrage wirklich von uns kommt.

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

Verfügbare Ereignisse

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

Abonnements einsehen

show ergänzt die zehn letzten Zustellversuche mit ihrem Statuscode und, wenn einer fehlgeschlagen ist, dem Fehler – das genügt meist, um eine falsche URL von einem Empfänger zu unterscheiden, der die Payload ablehnt.

nexdns webhook list
nexdns webhook show <webhook-id>

Testereignis senden

Stellt eine Testzustellung in die Warteschlange. Ein Erfolg bedeutet hier, dass die Plattform das Ereignis angenommen hat, nicht dass Ihr Endpunkt geantwortet hat – das Ergebnis lesen Sie mit nexdns webhook show zurück.

nexdns webhook test <webhook-id>

Abonnement ändern oder pausieren

Übergeben Sie nur, was sich ändert; der Befehl liest das aktuelle Abonnement und sendet den Rest unverändert mit. Mit --active=false stoppen Sie die Zustellungen, ohne den Endpunkt zu löschen, mit --force löschen Sie ohne Bestätigungsabfrage.

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

Konto & Konfiguration

Lesen Sie zurück, zu welchem Konto ein Token gehört, welchen Tarif es trägt und welche API-Schlüssel vorhanden sind.

nexdns account info
nexdns account api-keys

Dauerhafte Einstellungen

Die Konfigurationsdatei enthält fünf Einstellungen – api-url, token, output, color und timeout –, die alle über das CLI gelesen und geschrieben werden können. config view gibt die effektive Konfiguration aus, einschließlich der Herkunft des Tokens.

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

Umgebungsvariablen

Zu jeder Einstellung gibt es außerdem eine Umgebungsvariable – in CI-Runnern meist der übliche Weg. NEXDNS_CONFIG verweist auf eine alternative Konfigurationsdatei, praktisch, wenn mehrere Konten von einem Rechner aus gesteuert werden.

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

Gespeichertes Token entfernen

Löscht das Token aus der Konfigurationsdatei. Die Datei selbst und eine darin gespeicherte API-URL bleiben erhalten.

nexdns auth logout

Shell-Vervollständigung

Vervollständigungsskripte werden für bash, zsh, fish und PowerShell erzeugt.

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

Skripting & CI

Das CLI ist darauf ausgelegt, von Pipelines gesteuert zu werden: Jeder Fehlerfall hat einen eigenen Exit-Code, Rückfragen werden abgelehnt, statt zu blockieren, und nichts Destruktives passiert ohne ausdrückliche Anforderung.

Exit-Codes

Ein falsch geschriebener Unterbefehl endet mit 2, statt die Hilfe auszugeben und erfolgreich zu sein – so kann ein Tippfehler in einer Pipeline nicht als abgeschlossene Operation durchgehen.

Bestätigungsabfragen

Destruktive Befehle fragen vor der Ausführung nach. Ohne Terminal – und das ist jeder CI-Runner – wird die Abfrage abgelehnt, der Befehl endet mit 0 und hat nichts geändert; übergeben Sie also --force, wenn Sie es ernst meinen.

Fehler, die früher stillschweigend durchgingen

• Eine nicht aufgelöste ${VAR} in nexdns.yaml stoppt den Lauf und nennt jede Variable ohne Wert, anstatt den literalen Text in einen Eintrag zu schreiben.
• Ein --zone, das keine Zone in der Datei benennt, ist ein Fehler.
• zone check endet mit einem Exit-Code ungleich null, wenn eine Propagierungsprüfung fehlschlägt.
• apply --confirm endet mit einem Exit-Code ungleich null, wenn eine Operation fehlgeschlagen ist, und meldet, wie viele.

Anfrage-Limits und Massenoperationen

Das API-Budget gilt pro Konto und pro Tarif, in einem gleitenden Fenster von einer Minute. Das CLI liest das Budget aus jeder Antwort und wartet auf den Fensterwechsel, bevor es das Budget überschreiten würde – ein großer Import läuft dadurch vollständig durch, statt Einträge zu verlieren, und dauert lediglich länger. Ein Limit mit längerem Fenster, etwa die Obergrenze dafür, wie oft eine Zone die Nameserver-Gruppe wechseln darf, wird gemeldet statt abgewartet.

Docker

Das CLI ist als Docker-Image verfügbar. Übergeben Sie Ihr API-Token über die Umgebungsvariable NEXDNS_TOKEN.

Befehle ausführen

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

Zonendatei importieren

Binden Sie ein lokales Verzeichnis ein, um Zonendateien in den Container zu übergeben:

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

Globale Flags

Die folgenden Flags sind bei allen Befehlen verfügbar:

Jedes dieser Flags liest auch eine Umgebungsvariable: NEXDNS_TOKEN, NEXDNS_API_URL, NEXDNS_TIMEOUT und NEXDNS_CONFIG. NO_COLOR deaktiviert die Farbausgabe unabhängig von --color.

Terraform

Der NexDNS Terraform-Provider ermöglicht die Verwaltung von Zonen und Einträgen als Terraform-Ressourcen. Installieren Sie den Provider aus der Terraform Registry und konfigurieren Sie ihn mit Ihrem API-Token.

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"
}

DNSControl-Integration

DNSControl ist ein DNS-as-Code-Tool von Stack Overflow. Verwenden Sie den NexDNS-Provider, um Ihre Zonen deklarativ zu verwalten. Der Provider ist ab DNSControl 4.46.0 enthalten.

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 ist ein DNS-as-Code-Tool von GitHub. Installieren Sie den NexDNS-Provider und konfigurieren Sie ihn als Quelle oder Ziel in Ihrer OctoDNS-Konfiguration.

Provider installieren

pip install octodns-nexdns

Konfigurationsdatei 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

Zonendatei 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.