# DDNS Command Line Arguments Reference

This document provides detailed usage instructions for DDNS command line arguments. Command line arguments can override settings from configuration files and environment variables, having the **highest priority**.

## Basic Usage

Use `-h` to view the parameter list:

```bash
# ddns [options]
ddns -h
```

Or using Python source code:

```bash
# python run.py [options]
python -m ddns -h
```

## Parameter List

### List Parameter Usage

For list-type parameters that support multiple values (such as `--ipv4`, `--ipv6`, `--index4`, `--index6`, `--proxy`, etc.), you can specify multiple values using the following two methods:

#### Method 1: Repeat Parameter Names (Recommended)

```bash
ddns --ipv4 example.com --ipv4 www.example.com --ipv4 api.example.com
ddns --index4 public --index4 0 --index4 "regex:192\\.168\\..*"
ddns --proxy SYSTEM --proxy DIRECT
```

#### Method 2: Space-Separated

```bash
ddns --ipv4 example.com www.example.com api.example.com
ddns --index4 public 0 "regex:192\\.168\\..*"
ddns --proxy SYSTEM DIRECT
```

#### Parameters with Spaces

If parameter values contain spaces, use quotes:

```bash
ddns --line "China Telecom" "China Unicom" "China Mobile"
ddns --index4 "url:http://ip.example.com/api?type=ipv4" public
```

#### Unsupported Usage

```bash
# ❌ Comma-separated not supported
ddns --ipv4 "example.com,www.example.com"
ddns --ipv4=example.com,www.example.com
```

### Parameter Details

| Parameter          |     Type    | Description                                                                                                                                                               | Example                                                  |
| --------------- | :---------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `-h, --help`    |     Flag    | Show help message and exit                                                                                                                                                | `--help`                                                 |
| `-v, --version` |     Flag    | Show version information and exit                                                                                                                                         | `--version`                                              |
| `-c, --config`  | String List | Specify configuration file path, supports multiple config files and remote HTTP(S) URLs                                                                                              | `--config config.json` or `--config config1.json --config config2.json` <br> `--config https://ddns.newfuture.cc/tests/config/debug.json`                                   |
| `--new-config`  | Flag/String | Generate a new config file (optional file path)                                                                                                                           | `--new-config` <br> `--new-config=config.json`           |
| `--debug`       |     Flag    | Enable debug mode                                                                                                                                                         | `--debug`                                                |
| `--dns`         |    Choice   | [DNS Providers](../providers/) include:<br>51dns, alidns, aliesa, callback, cloudflare,<br>debug, dnscom, dnspod\_com, dnspod, edgeone, he,<br>huaweidns, noip, tencentcloud | `--dns cloudflare`                                       |
| `--endpoint`    |    String   | Custom API endpoint URL (useful for self-hosted services)                                                                                                                 | `--endpoint https://api.private.com`                     |
| `--id`          |    String   | API Access ID, email, or Access Key                                                                                                                                       | `--id user@example.com`                                  |
| `--token`       |    String   | API token or secret key                                                                                                                                                   | `--token abcdef123456`                                   |
| `--ipv4`        | String List | List of domain names for IPv4, supports repeated parameters or space-separated                                                                                                     | `--ipv4 test.com 4.test.com` or `--ipv4 test.com --ipv4 4.test.com`                      |
| `--ipv6`        | String List | List of domain names for IPv6, supports repeated parameters or space-separated                                                                                                     | `--ipv6 test.com` or `--ipv6 test.com ipv6.test.com`                                        |
| `--index4`      |     List    | Methods to retrieve IPv4 address, supports: number, default, public,<br>url:, regex:, cmd:, shell:                                                                        | `--index4 public 0` or `--index4 public --index4 "regex:192\\.168\\..*"` |
| `--index6`      |     List    | Methods to retrieve IPv6 address, supports: number, default, public,<br>url:, regex:, cmd:, shell:                                                                        | `--index6 0 public` or `--index6 0 --index6 public`                      |
| `--ttl`         |   Integer   | DNS record TTL time in seconds                                                                                                                                            | `--ttl 600`                                              |
| `--line`        |    String   | DNS resolution line (e.g. ISP line)                                                                                                                                       | `--line 电信` <br> `--line telecom`                        |
| `--proxy`       | String List | HTTP proxy settings, supports: `http://host:port`, `DIRECT`(direct), `SYSTEM`(system proxy)                                | `--proxy SYSTEM DIRECT` or `--proxy http://127.0.0.1:1080 --proxy DIRECT`    |
| `--cache`       | Flag/String | Enable cache or specify custom cache path                                                                                                                                 | `--cache` <br> `--cache=/path/to/cache`                  |
| `--cache-max-age`, `--cache_max_age` | Non-negative integer (seconds) | Maximum cache file age; default `259200` seconds, `0` clears an existing cache on every invocation | `--cache-max-age 86400` |
| `--no-cache`    |     Flag    | Disable cache (equivalent to `--cache=false`)                                                                                                                             | `--no-cache`                                             |
| `--ssl`         |    String   | SSL certificate verification: true, false, auto, or file path                                                                                                             | `--ssl false` <br> `--ssl=/path/to/ca-certs.crt`         |
| `--no-ssl`      |     Flag    | Disable SSL verification (equivalent to `--ssl=false`)                                                                                                                    | `--no-ssl`                                               |
| `--log_file`    |    String   | Log file path. If not set, logs are output to the console                                                                                                                 | `--log_file=/var/log/ddns.log`                           |
| `--log_level`   |    String   | Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL                                                                                                                      | `--log_level=ERROR`                                      |
| `--log_format`  |    String   | Log format string (compatible with Python `logging` module)                                                                                                               | `--log_format="%(asctime)s:%(message)s"`                 |
| `--log_datefmt` |    String   | Date/time format string for logs                                                                                                                                          | `--log_datefmt="%Y-%m-%d %H:%M:%S"`                      |

`--cache-max-age` controls whole-file cache expiry, in seconds. The default is 259200 (72 hours). On the next invocation, a cache is stale when `now - mtime >= cache_max_age` or its mtime is in the future; `0` clears an existing cache every time. This is distinct from DNS TTL. The flat JSON file has one mtime, so any cache write refreshes the age for every entry. The format is unchanged and no migration is performed; existing shared-cache limitations remain.

#### Task Subcommand Parameters

| Parameter          |     Type    | Description                                                                                                                                                               | Example                                                  |
| --------------- | :---------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `--install`, `-i` | Integer (Optional) | Install scheduled task with update interval in minutes (default: 5). **Automatically overwrites existing tasks** | `--install`, `--install 10` |
| `--uninstall`   |     Flag    | Uninstall the installed scheduled task                                                                                                                                    | `--uninstall`                                           |
| `--status`      |     Flag    | Show scheduled task installation status and running information                                                                                                           | `--status`                                               |
| `--enable`      |     Flag    | Enable the installed scheduled task                                                                                                                                       | `--enable`                                               |
| `--disable`     |     Flag    | Disable the installed scheduled task                                                                                                                                      | `--disable`                                              |
| `--scheduler`   |   Choice    | Specify scheduler type. Supports: auto (automatic), systemd, cron, launchd, schtasks                                                                                    | `--scheduler systemd`, `--scheduler auto`                |

> **Important Notes**:
>
> - The `--install` command **automatically overwrites** scheduled tasks without needing to check or uninstall existing tasks first.
> - This design simplifies the task management process and avoids manual uninstallation procedures.
> - The `task` subcommand supports all main DDNS configuration parameters (such as `--dns`, `--id`, `--token`, `--ipv4`, `--ipv6`, etc.), which will be saved and passed to the scheduled task for execution.
> - Command line only parameters: `--debug`, `--new-config`, `--no-cache`, `--no-ssl`, `--help`, `--version`.

> **Note**: Where `--debug`, `--new-config`, `--no-cache`, `--no-ssl`, `--help`, `--version` are command line only parameters.

## DNS Provider Values

DDNS supports the following DNS providers:

- **51dns** (alias for dnscom): DNS.COM service
- **alidns**: Alibaba Cloud DNS
- **aliesa**: Alibaba Cloud ESA (Edge Security Acceleration)
- **callback**: Custom callback/webhook
- **cloudflare**: Cloudflare DNS
- **debug**: Debug provider (prints IP without updating DNS)
- **dnscom**: DNS.COM service (same as 51dns)
- **dnspod**: DNSPod (China)
- **dnspod_com**: DNSPod International
- **he**: Hurricane Electric DNS
- **huaweidns**: Huawei Cloud DNS
- **noip**: No-IP Dynamic DNS
- **tencentcloud**: Tencent Cloud DNS
- **edgeone**: Tencent Cloud EdgeOne

## IP Detection Methods

### IPv4/IPv6 Detection (`--index4`, `--index6`)

- **number** (0, 1, 2...): Use IP of the Nth network interface
- **default**: System's default external IP
- **public**: Get public IP from external services with automatic failover
- **url:ADDRESS**: Get IP from specific URL
- **regex:PATTERN**: Extract IP using regex pattern
- **cmd:COMMAND**: Get IP from command output
- **shell:COMMAND**: Get IP from shell command

Examples:

```bash
# Use public IP detection
ddns --dns cloudflare --index4 public

# Use multiple detection methods (fallback)
ddns --dns cloudflare --index4 public --index4 "regex:192\\.168\\..*"

# Use custom URL for IP detection
ddns --dns cloudflare --index4 "url:http://api.ipify.org"

# Use command output for IP
ddns --dns cloudflare --index4 "cmd:hostname -I | awk '{print $1}'"
```

## Usage Examples

### Basic Configuration File Usage

```bash
# Use default configuration file
ddns

# Use specified configuration file
ddns -c /path/to/config.json

# Use multiple configuration files
ddns -c cloudflare.json -c dnspod.json

# Use remote configuration file
ddns -c https://ddns.newfuture.cc/tests/config/debug.json

# Use remote configuration with proxy
ddns -c https://config.example.com/ddns.json --proxy http://proxy:8080

# Generate new configuration file
ddns --new-config config.json
```

### Command Line Configuration

```bash
# Simplest configuration - DNSPod
ddns --dns dnspod --id 12345 --token mytokenkey --ipv4 example.com

# Cloudflare with API token
ddns --dns cloudflare --token your_api_token --ipv4 example.com

# Enable debug mode
ddns --dns cloudflare --token API_TOKEN --ipv4 example.com --debug

# Multiple domains (space-separated)
ddns --dns cloudflare --token API_TOKEN \
     --ipv4 example.com www.example.com --ipv6 example.com

# Multiple domains (repeated parameters)
ddns --dns cloudflare --token API_TOKEN \
     --ipv4 example.com --ipv4 www.example.com --ipv6 example.com
```

### Provider-Specific Examples

```bash
# Alibaba Cloud DNS
ddns --dns alidns --id your_access_key --token your_secret_key --ipv4 example.com

# Huawei Cloud DNS  
ddns --dns huaweidns --id your_access_key --token your_secret_key --ipv4 example.com

# No-IP
ddns --dns noip --id your_username --token your_password --ipv4 example.com

# Custom Callback (GET request)
ddns --dns callback --id "https://api.example.com/ddns?domain=__DOMAIN__&ip=__IP__" --ipv4 example.com
```

### Advanced Configuration

```bash
# Complete configuration with proxy, TTL, and custom IP detection (space-separated)
ddns --dns cloudflare --token API_TOKEN \
     --ipv4 example.com www.example.com \
     --index4 public "regex:2001:.*" \
     --ttl 300 --proxy http://127.0.0.1:1080 DIRECT \
     --cache=/var/cache/ddns.cache \
     --log_level=INFO --log_file=/var/log/ddns.log

# Complete configuration (repeated parameters)
ddns --dns cloudflare --token API_TOKEN \
     --ipv4 example.com --ipv4 www.example.com \
     --index4 public --index6 "regex:2001:.*" \
     --ttl 300 --proxy http://127.0.0.1:1080 --proxy DIRECT \
     --cache=/var/cache/ddns.cache \
     --log_level=INFO --log_file=/var/log/ddns.log

# ISP line configuration (for Chinese providers)
ddns --dns dnspod --id 12345 --token mytokenkey \
     --ipv4 telecom.example.com --line 电信

# Use remote configuration file
ddns -c https://ddns.newfuture.cc/tests/config/debug.json --debug

# Remote configuration with proxy
ddns -c https://config.example.com/ddns.json \
     --proxy http://proxy.company.com:8080

# Disable cache and SSL verification
ddns --dns alidns --id ACCESS_KEY --token SECRET_KEY \
     --ipv4 example.com --no-cache --no-ssl
```

## Important Notes

1. **Command Line Parameter Priority**: Command line arguments have the highest priority and will override settings in configuration files and environment variables.

2. **Quote Usage**: For parameter values that contain spaces or special characters, please use quotes, for example: `--log_format="%(asctime)s: %(message)s"`.

3. **List Parameter Configuration**: For multi-value parameters (such as `--ipv4`, `--ipv6`, `--index4`, `--index6`, `--proxy`, etc.), two specification methods are supported:

   ```bash
   # ✅ Method 1: Repeat parameter names (recommended)
   ddns --ipv4 example.com --ipv4 sub.example.com --ipv4 api.example.com
   ddns --index4 public --index4 0 --index4 "regex:192\\.168\\..*"
   ddns --proxy http://127.0.0.1:1080 --proxy DIRECT
   
   # ✅ Method 2: Space-separated
   ddns --ipv4 example.com sub.example.com api.example.com
   ddns --index4 public 0 "regex:192\\.168\\..*"
   ddns --proxy http://127.0.0.1:1080 DIRECT
   
   # ✅ Parameter values with spaces use quotes
   ddns --line "China Telecom" "China Unicom"
   
   # ❌ Incorrect usage - not supported
   ddns --ipv4 "example.com,sub.example.com"    # Comma-separated not supported
   ddns --ipv4=example.com,sub.example.com      # Equals + comma not supported
   ```

4. **Debug Mode**: The `--debug` parameter is only effective as a command line argument; debug settings in configuration files will be ignored.

5. **Regular Expressions**: When using regular expressions, special characters need to be properly escaped. It's recommended to use quotes, for example: `--index4 "regex:192\\.168\\..*"`.

## Web console and in-process scheduling

Providing `--interval` automatically starts the long-running console, so the `web` word is optional. The Web process also owns periodic synchronization and exposes [MCP `2026-07-28` Streamable HTTP](mcp.md) at `/mcp` on the same listener. The existing `ddns web` form remains compatible.

```bash
ddns -c /etc/ddns/config.json --interval 5 --open
```

| Option | Description |
|--------|-------------|
| `-c, --config FILE` | Select one local configuration file managed by the console |
| `--host` | Shared Web/MCP bind host; defaults to `127.0.0.1` and accepts a LAN address or `0.0.0.0` / `::` |
| `--port` | Shared Web/MCP port, default `9876`; use `0` to let the OS select an available port |
| `--http-token` | Shared Web API and HTTP MCP token; visible ASCII without spaces |
| `--http-origin ORIGIN` | Exact HTTP(S) origin allowed to access `/mcp` cross-origin; repeatable |
| `--interval MINs` | Built-in interval for the current Web process, from 1 to 1440 minutes, default 5 |
| `--open` | Open the browser after startup |

Listener precedence is command line > root JSON `http` > `DDNS_HTTP_*` environment variables > `127.0.0.1:9876`. When loopback has no token, the Web APIs (including full configuration and provider credentials) and `/mcp` are unauthenticated. A non-loopback or wildcard listener requires a non-empty visible-ASCII token without spaces. With a token, the page continues to use `X-DDNS-Token` and also accepts `Authorization: Bearer`; MCP uses the Bearer form.

DDNS does not provide TLS. Put LAN listeners behind a trusted HTTPS reverse proxy that preserves `Authorization`, `Host`, and `Origin`. Browser access through a TLS-terminating proxy must list the exact public HTTPS origin in `http.origins` or `--http-origin`, even when the public page appears same-origin; native MCP clients may omit `Origin`.

`--interval` is the explicit Web mode signal; a top-level JSON `interval` also makes `ddns -c FILE` enter Web mode automatically. Precedence is command-line `--interval` > JSON `interval` > the 5-minute default. Saving an interval applies it immediately; HTTP listener and authentication changes require a restart.

When an enabled `ddns task` system task is detected, Web scheduling stops and reports a conflict. Explicitly take over in the console or run `ddns task --disable` first. Do not let multiple Web, MCP, or system-task processes update the same configuration concurrently.

See [MCP Server](mcp.md) for client configuration, stdio and HTTP usage, tools, and protocol limits.

## Task Management

For headless deployments, DDNS supports system scheduled tasks through the `task` subcommand, which automatically detects the system and selects the appropriate scheduler.

### Key Features

- **Smart Installation**: The `--install` command automatically overwrites existing tasks, simplifying the installation process
- **Cross-Platform Support**: Automatically detects system and selects the best scheduler
- **Complete Configuration**: Supports all DDNS configuration parameters

### Task Subcommand Usage

```bash
# View help
ddns task --help

# Check task status
ddns task --status

# Install scheduled task (default 5-minute interval)
ddns task --install

# Install scheduled task with custom interval (minutes)
ddns task --install 10
ddns task -i 15

# Specify scheduler type for installation
ddns task --install 5 --scheduler systemd
ddns task --install 10 --scheduler cron
ddns task --install 15 --scheduler auto

# Enable installed scheduled task
ddns task --enable

# Disable installed scheduled task
ddns task --disable

# Uninstall installed scheduled task
ddns task --uninstall
```

### Supported Schedulers

DDNS automatically detects the system and chooses the most appropriate scheduler:

- **Linux**: systemd (preferred) or cron
- **macOS**: launchd (preferred) or cron  
- **Windows**: schtasks

### Scheduler Selection Guide

| Scheduler | Supported Systems | Description | Recommendation |
|-----------|-------------------|-------------|----------------|
| `auto` | All systems | Automatically detects system and selects the best scheduler | ⭐⭐⭐⭐⭐ |
| `systemd` | Linux | Modern Linux standard timer with complete functionality | ⭐⭐⭐⭐⭐ |
| `cron` | Unix-like | Traditional Unix scheduled tasks with good compatibility | ⭐⭐⭐⭐ |
| `launchd` | macOS | macOS native task scheduler | ⭐⭐⭐⭐⭐ |
| `schtasks` | Windows | Windows Task Scheduler | ⭐⭐⭐⭐⭐ |

### Parameter Description

| Parameter | Description |
|-----------|-------------|
| `--status` | Show scheduled task installation status and running information |
| `--install [minutes]`, `-i [minutes]` | Install scheduled task with update interval (default: 5 minutes). **Automatically overwrites existing tasks** |
| `--uninstall` | Uninstall installed scheduled task |
| `--enable` | Enable installed scheduled task |
| `--disable` | Disable installed scheduled task |
| `--scheduler` | Specify scheduler type. Supports: auto, systemd, cron, launchd, schtasks |

> **Installation Behavior**:
>
> - The `--install` command always executes installation directly, without prior checking or uninstalling.
> - Any existing DDNS scheduled task in the system will be automatically replaced with the new configuration.
> - This design simplifies task management and avoids the hassle of manual uninstallation, enabling one-click task updates.
>
> **Configuration Parameter Support**: The `task` subcommand supports all DDNS configuration parameters, which will be passed to the scheduled task for execution.

### Permission Requirements

Different schedulers require different permissions:

- **systemd**: Requires root privileges (`sudo`)
- **cron**: Regular user privileges
- **launchd**: Regular user privileges
- **schtasks**: Administrator privileges required

### Task Management Examples

```bash
# Check current status
ddns task --status

# Quick install (automatically overwrites existing tasks)
ddns task --install

# Install 10-minute interval scheduled task with specified config file
ddns task --install 10 -c /etc/ddns/config.json

# Install scheduled task with direct DDNS parameters (no config file needed)
ddns task --install 5 --dns cloudflare --id user@example.com --token API_TOKEN --ipv4 example.com

# Install scheduled task with advanced configuration parameters
ddns task --install 10 --dns dnspod --id 12345 --token secret \
          --ipv4 example.com --ttl 600 --proxy http://proxy:8080 \
          --log_file /var/log/ddns.log --log_level INFO

# Specify scheduler type for installation
ddns task --install 5 --scheduler systemd --dns cloudflare --id user@example.com --token API_TOKEN --ipv4 example.com

# Force use cron scheduler (for Linux systems without systemd)
ddns task --install 10 --scheduler cron -c config.json

# Force use launchd on macOS
ddns task --install 15 --scheduler launchd --dns dnspod --id 12345 --token secret --ipv4 example.com

# Use schtasks on Windows
ddns task --install 5 --scheduler schtasks --dns cloudflare --id user@example.com --token API_TOKEN --ipv4 example.com

# Install systemd timer on Linux with sudo
sudo ddns task --install 5 -c /etc/ddns/config.json

# Update task configuration (automatic overwrite)
ddns task --install 15 --dns cloudflare --id user@example.com --token NEW_TOKEN --ipv4 example.com

# Enable installed task
ddns task --enable

# Disable task (doesn't delete, just stops execution)
ddns task --disable

# Completely uninstall scheduled task
ddns task --uninstall
```

### Using with Configuration Files

The `task` subcommand works perfectly with configuration files, supporting multiple configuration methods:

```bash
# Use local configuration file
ddns task --install 10 -c config.json

# Use multiple configuration files
ddns task --install 5 -c cloudflare.json -c dnspod.json

# Use remote configuration file
ddns task --install 15 -c https://config.example.com/ddns.json

# Configuration file + command line parameter override
ddns task --install 10 -c config.json --debug --ttl 300

# Specify scheduler type + configuration file
ddns task --install 5 --scheduler cron -c config.json

# Use remote configuration file + specify scheduler
ddns task --install 10 --scheduler systemd -c https://config.example.com/ddns.json
```

### Scheduler Usage Examples

Choose the appropriate scheduler based on different systems and requirements:

```bash
# Automatic selection (recommended, let system choose the best scheduler)
ddns task --install 5 --scheduler auto

# Linux system choices
ddns task --install 5 --scheduler systemd  # Preferred choice, full functionality
ddns task --install 5 --scheduler cron     # Backup choice, good compatibility

# macOS system choices
ddns task --install 5 --scheduler launchd  # Preferred choice, system native
ddns task --install 5 --scheduler cron     # Backup choice, good compatibility

# Windows system choices
ddns task --install 5 --scheduler schtasks # Only choice, Windows Task Scheduler
```

### Debugging Installation Issues

```bash
# Enable debug mode to view detailed installation process
ddns task --install 5 --debug

# View task status and configuration
ddns task --status --debug

# View status of specified scheduler
ddns task --status --scheduler systemd --debug
```

## Configuration Priority

DDNS uses the following priority order (highest to lowest):

1. **Command line arguments** (highest priority)
2. **JSON configuration file**
3. **Environment variables** (lowest priority)

This means command line arguments will override any settings in configuration files or environment variables.

## See Also

- [Environment Variables Configuration](env.md)
- [JSON Configuration File](json.md)
- [Docker Usage](../docker.md)
- [Provider-specific Configuration](../providers/)