alibaba-dns-cli

A command-line interface for managing Alibaba Cloud DNS records. Built with Bun runtime with native TypeScript support.

⚠️ Important: This project is Bun-only. Node.js is not supported. You must have Bun installed to run this CLI.

Features

• List, add, update, and delete DNS records
• Enable/disable DNS records
• Table and JSON output formats
• Filter records by type or hostname
• Pagination support for large record sets

Requirements

• Bun 1.0.0 or higher (required - Node.js is not supported)
• Alibaba Cloud account with DNS access
• RAM user with AliyunDNSFullAccess policy

No Node.js Support: This CLI is built exclusively for Bun runtime. It will not work with Node.js.

Installation

Using npm (Recommended)

# Install globally via npm
npm install -g alibaba-dns-cli

# Run directly after installation
alibaba-dns-cli --help

Using bunx (No Installation Required)

# Run directly without installation
bunx alibaba-dns-cli --help

# Run any command
bunx alibaba-dns-cli list example.com

Development Installation

# Clone the repository
git clone https://github.com/user/alibaba-dns-cli.git
cd alibaba-dns-cli

# Install dependencies
bun install

# Link globally
bun link

Configuration

Set your Alibaba Cloud credentials as environment variables:

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret

# Optional: Custom endpoint (default: alidns.cn-hangzhou.aliyuncs.com)
export ALIDNS_ENDPOINT=alidns.ap-southeast-1.aliyuncs.com

# Optional: Custom region (default: cn-hangzhou)
export ALIDNS_REGION=ap-southeast-1

Available Endpoints

| Region | Endpoint | | ---------------- | ------------------------------------ | | China (Hangzhou) | alidns.cn-hangzhou.aliyuncs.com | | China (Shanghai) | alidns.cn-shanghai.aliyuncs.com | | China (Beijing) | alidns.cn-beijing.aliyuncs.com | | China (Shenzhen) | alidns.cn-shenzhen.aliyuncs.com | | Singapore | alidns.ap-southeast-1.aliyuncs.com | | Global | alidns.aliyuncs.com |

Quick Start

# Using bunx (no installation needed)
# 1. Add a new A record
bunx alibaba-dns-cli add fornever.org --rr www --type A --value 1.2.3.4 --ttl 600
# Output: Record added successfully

# 2. Update the record value (no record ID needed!)
bunx alibaba-dns-cli update fornever.org --rr www --type A --value 5.6.7.8
# Output: Record updated successfully

# 3. Disable the record temporarily
bunx alibaba-dns-cli disable fornever.org --rr www --type A
# Output: Record www.fornever.org (A) disabled successfully

# 4. Enable it again
bunx alibaba-dns-cli enable fornever.org --rr www --type A
# Output: Record www.fornever.org (A) enabled successfully

# 5. List to verify
bunx alibaba-dns-cli list fornever.org --type A

# 6. Delete when done
bunx alibaba-dns-cli delete fornever.org --rr www --type A --force
# Output: Record www.fornever.org (A) deleted successfully

Note: All commands shown above use bunx alibaba-dns-cli. If you installed globally via npm, you can simply use alibaba-dns-cli instead.

Usage

All examples use bunx alibaba-dns-cli. If installed globally via npm, use alibaba-dns-cli instead.

List DNS Records

# List all records for a domain
bunx alibaba-dns-cli list example.com

# List only A records
bunx alibaba-dns-cli list example.com --type A

# Filter by hostname (RR)
bunx alibaba-dns-cli list example.com --rr www

# Output as JSON
bunx alibaba-dns-cli list example.com --json

# With pagination
bunx alibaba-dns-cli list example.com --page 1 --size 50

Add DNS Record

# Add an A record
bunx alibaba-dns-cli add example.com --rr www --type A --value 1.2.3.4

# Add with custom TTL
bunx alibaba-dns-cli add example.com --rr www --type A --value 1.2.3.4 --ttl 600

# Add an MX record with priority
bunx alibaba-dns-cli add example.com --rr @ --type MX --value mail.example.com --priority 10

# Add a CNAME record
bunx alibaba-dns-cli add example.com --rr blog --type CNAME --value myblog.example.com

Update DNS Record

# Update a record by domain + RR + type (no record ID needed!)
bunx alibaba-dns-cli update example.com --rr www --type A --value 5.6.7.8

# Update with new TTL
bunx alibaba-dns-cli update example.com --rr www --type A --value 5.6.7.8 --ttl 300

Delete DNS Record

# Delete a record by domain + RR + type (requires --force or --yes flag)
bunx alibaba-dns-cli delete example.com --rr www --type A --force

# Using --yes alias
bunx alibaba-dns-cli delete example.com --rr www --type A --yes

Enable/Disable Records

# Disable a record by domain + RR + type
bunx alibaba-dns-cli disable example.com --rr www --type A

# Enable a record
bunx alibaba-dns-cli enable example.com --rr www --type A

Help

# General help
bunx alibaba-dns-cli --help

# Command-specific help
bunx alibaba-dns-cli list --help
bunx alibaba-dns-cli add --help

Supported Record Types

• A - IPv4 address
• AAAA - IPv6 address
• CNAME - Canonical name
• MX - Mail exchange (supports priority)
• TXT - Text record
• NS - Name server
• SRV - Service record
• CAA - Certificate Authority Authorization

Project Structure

.
├── src/
│   ├── cli.ts           # CLI entry point (Commander.js)
│   ├── dns-client.ts    # Alibaba DNS SDK wrapper
│   ├── config.ts        # Configuration management
│   ├── formatter.ts     # Output formatting (table/JSON)
│   ├── types.ts         # TypeScript interfaces
│   └── index.ts         # Module exports
├── test/
│   ├── config.test.ts
│   ├── formatter.test.ts
│   ├── types.test.ts
│   └── index.test.ts
├── package.json
├── AGENTS.md            # AI coding agents guide
└── README.md

Development

# Run the CLI directly
bun src/cli.ts --help

# Run tests
bun test

# Run a single test file
bun test test/config.test.ts

# Lint code
bun run lint

# Fix lint issues
bun run lint:fix

# Format code
bun run format

# Full validation (CI)
bun run lint && bun run format:check && bun test

Programmatic Usage

Programmatic Usage

You can also use the library programmatically:

import { createDnsClient, loadConfig } from "alibaba-dns-cli";

const config = loadConfig();
const client = createDnsClient(config);

// List records
const records = await client.listRecords({ domainName: "example.com" });

// Add a record
const newRecord = await client.addRecord({
  domainName: "example.com",
  rr: "www",
  type: "A",
  value: "1.2.3.4",
});

// Find a record by domain + RR + type
const record = await client.findRecord("example.com", "www", "A");

// Update a record (using recordId from findRecord)
if (record) {
  await client.updateRecord({
    recordId: record.recordId,
    rr: "www",
    type: "A",
    value: "5.6.7.8",
  });

  // Enable/disable
  await client.setRecordStatus(record.recordId, false); // disable
  await client.setRecordStatus(record.recordId, true); // enable

  // Delete a record
  await client.deleteRecord(record.recordId);
}

License

MIT

Runtime Requirement

⚠️ This project requires Bun runtime and does not support Node.js.

This CLI is built exclusively for Bun, a modern JavaScript runtime. If you don't have Bun installed, you can install it with:

# On macOS/Linux
curl -fsSL https://bun.sh/install | bash

# On Windows (PowerShell)
irm bun.sh/install.ps1 | iex

# On Windows (PowerShell with specific version)
powershell -c "irm bun.sh/install.ps1|iex"

To verify your Bun installation:

bun --version

If you need a Node.js-compatible version of this tool, please consider using alternative DNS management tools or contribute to this project to add Node.js support.