chirag127/ndns

ndns

Complete NextDNS account CLI — full official-API coverage in a single-file TypeScript binary. Runs on Deno or Bun.

Docs + command reference: <https://ndns.oriz.in · Repo: <https://github.com/chirag127/ndns

ndns drives your entire NextDNS account from the terminal — profiles, deny/allow lists, blocklists, native tracker feeds, security & parental controls, privacy toggles, analytics, and live logs. It fills the gap left by nextdns/nextdns (forwarder-only) and third-party libraries (all narrow or stale) by covering the full official REST API in one dependency-light TypeScript file.

⭐ If this is useful, please star the repo — it helps others find it.

Beta notice

The NextDNS API is BETA and subject to breaking changes. See the official docs. Report breakage via GitHub issues.

How it works

flowchart LR
    U[User] --> CLI
    subgraph CLI [ndns CLI]
      A[args.ts<br/>parse argv + flags] --> C[client.ts<br/>typed API client]
      A --> CMD[commands/<br/>profile · lists · analytics · logs …]
      CMD --> C
    end
    C -->|NEXTDNS_API_KEY| API[NextDNS official<br/>REST API]
    API --> C
    G[gen:site] -.publishes docs.-> SITE[ndns.oriz.in]

Features

• Full official-API coverage — profiles, denylist/allowlist, blocklists, native feeds, security, parental controls, privacy, settings, analytics (11 endpoints), logs (incl. SSE stream), and config export/import.
• Two runtimes — install via Deno or Bun, or grab a prebuilt binary from GitHub Releases.
• Single-file TS — easy to audit, easy to vendor.
• Flexible output — table, json, or csv for every command.
• Time-series analytics — --series with configurable interval + timezone.
• Backup/restore — full profile config export and import.

• Bulk workflows — import/export deny/allow lists (see examples/).

Tech stack

• Deno 2.9+ / Bun 1.3+
• TypeScript — single-file entry (src/mod.ts)
• @std/ (Deno standard library) + @deno/gfm (docs-site generation)
• Published to npm as @chirag127/ndns

Repo structure

src/
├── mod.ts          # entry point
├── args.ts         # argv + flag parsing
├── client.ts       # typed NextDNS REST client
├── commands/       # one module per command group
└── util/           # shared helpers
examples/           # bulk-import-hagezi.sh, daily-summary.sh, sync-two-profiles.sh
.github/workflows/  # ci, pages (docs → ndns.oriz.in), release, prerelease

Install

# Deno (recommended)
deno install -grf --allow-net --allow-env --allow-read --allow-write \
  -n ndns https://raw.githubusercontent.com/chirag127/ndns/main/src/mod.ts

# Bun
bun install -g @chirag127/ndns

# Binary — download from GH releases
# https://github.com/chirag127/ndns/releases