czds-client

A command line helper for pulling the zone files you are authorized to access from the ICANN Centralized Zone Data Service (CZDS). If you need an account, sign up here: czds.icann.org.

Prerequisites

• Node.js 18 or newer
• Valid CZDS credentials with at least one approved TLD.

Configuration

Place a config.json beside package.json, or expose the same payload through the CZDS_CONFIG environment variable. All fields mirror the API specification:

{
  "icann.account.username": "user@example.com",
  "icann.account.password": "your-password",
  "authentication.base.url": "https://account-api.icann.org",
  "czds.base.url": "https://czds-api.icann.org",
  "tlds": ["example", "example2"],
  "working.directory": "./data",
  "user.agent": "czds-client-typescript/1.0.0 (+https://example.com/contact)"
}

• tlds (optional) limits downloads to the listed suffixes; leave it empty to fetch everything you are authorized to access.
• working.directory (optional) defaults to the current working directory; a zonefiles/ folder is created inside it.
• user.agent (optional) overrides the default czds-client-typescript/1.0.0; you can also supply CZDS_USER_AGENT.

Running via NPM:

$env:CZDS_CONFIG = Get-Content ./config.json -Raw
npm install czds-client
npx czds-client

Running from within the repo:

$env:CZDS_CONFIG = Get-Content ./config.json -Raw
npm run start

Library usage

import { run } from "czds-client";

await run();

The behavior is the same as the CLI: configuration is resolved from config.json, CZDS_CONFIG, and CZDS_USER_AGENT.

Troubleshooting

• HTTP 401 during authentication: double-check the username/password and that your IP is not rate-limited (the API allows eight attempts in five minutes).
• HTTP 403 or missing TLDs: verify that the requesting account has approved access for the requested zone and has accepted the latest Terms & Conditions in the CZDS portal.
• Unsupported media type (415): ensure the request body is JSON (Content-Type: application/json).