apertodns 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,29 @@
 # ApertoDNS CLI
 
-Dynamic DNS management from your terminal. Manage domains, tokens, and DNS updates with style.
+[![npm version](https://img.shields.io/npm/v/apertodns.svg)](https://www.npmjs.com/package/apertodns)
+[![license](https://img.shields.io/npm/l/apertodns.svg)](https://github.com/1r0n3d3v3l0per/apertodns/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/apertodns.svg)](https://nodejs.org)
+
+**Dynamic DNS management from your terminal.** Manage domains, tokens, API keys, and DNS updates with style.
+
+ApertoDNS is a free Dynamic DNS service that lets you point a subdomain to your dynamic IP address. Perfect for home servers, IoT devices, game servers, NAS systems, and remote access.
+
+## Features
+
+- **Easy Setup** - Login or register directly from CLI
+- **Multiple Domains** - Manage unlimited subdomains
+- **API Keys** - Create and manage API keys with granular scopes
+- **Auto Updates** - Set up cron or daemon mode for automatic IP updates
+- **Interactive Mode** - Beautiful terminal UI with menus
+- **JSON Output** - Machine-readable output for scripting
+- **IPv4 & IPv6** - Full dual-stack support
+- **Real-time Stats** - View usage statistics and logs
+- **Router/NAS Compatible** - Works with Synology, QNAP, and DynDNS2-compatible routers
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+- An ApertoDNS account ([register free](https://apertodns.com/register))
 
 ## Installation
 
@@ -8,28 +31,32 @@ Dynamic DNS management from your terminal. Manage domains, tokens, and DNS updat
 npm install -g apertodns
 ```
 
+Or use without installing:
+
+```bash
+npx apertodns --help
+```
+
 ## Quick Start
 
 ```bash
-# Setup (login or register)
+# 1. Setup (login or register)
 apertodns --setup
 
-# View dashboard
+# 2. View your dashboard
 apertodns --dashboard
 
-# List your domains
+# 3. List your domains
 apertodns --domains
 
-# Add a new domain
-apertodns --add-domain myserver.apertodns.com
-
-# Test DNS resolution
-apertodns --test google.com
+# 4. Force DNS update
+apertodns --force
 ```
 
 ## Commands
 
 ### Main Commands
+
 | Command | Description |
 |---------|-------------|
 | `--dashboard` | Complete dashboard with all info |
@@ -37,39 +64,185 @@ apertodns --test google.com
 | `--tokens` | List all your tokens |
 | `--stats` | Statistics and metrics |
 | `--logs` | Recent activity logs |
+| `--my-ip` | Show your current public IP |
 
 ### Domain Management
+
 | Command | Description |
 |---------|-------------|
-| `--add-domain <name>` | Create a new domain |
+| `--add-domain <name>` | Create a new subdomain |
 | `--delete-domain` | Delete a domain (interactive) |
 | `--test <domain>` | Test DNS resolution |
 
 ### Token Management
+
 | Command | Description |
 |---------|-------------|
 | `--enable <id>` | Enable a token |
 | `--disable <id>` | Disable a token |
 | `--toggle <id>` | Toggle token state |
+| `--verify` | Verify token validity |
+
+### API Keys
+
+| Command | Description |
+|---------|-------------|
+| `--api-keys` | List all API keys |
+| `--create-api-key <name>` | Create new API key |
+| `--delete-api-key <id>` | Delete an API key |
+| `--scopes` | Show available scopes |
+| `--api-key <key>` | Use API key for authentication |
 
 ### Configuration
+
 | Command | Description |
 |---------|-------------|
 | `--setup` | Guided setup (login/register) |
-| `--status` | Show current status |
-| `--force` | Force DNS update |
+| `--status` | Show current status and IP |
+| `--config` | Edit configuration |
+| `--logout` | Remove local configuration |
+| `--force` | Force DNS update now |
+
+### Daemon Mode
+
+| Command | Description |
+|---------|-------------|
+| `--daemon` | Start daemon mode (continuous updates) |
+| `--interval <sec>` | Update interval (default: 300s) |
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--cron` | Silent mode for cron jobs |
+| `--quiet` | Hide banner |
+| `--json` | JSON output (machine-readable) |
+| `-v, --version` | Show version |
+| `-h, --help` | Show help |
 
 ## Interactive Mode
 
-Run `apertodns` without arguments for interactive menu.
+Run `apertodns` without arguments for an interactive menu with all options.
+
+```bash
+apertodns
+```
+
+## Authentication Methods
+
+You can authenticate in 3 ways:
+
+1. **Interactive Login** - Run `apertodns --setup` (saves JWT to ~/.config/apertodns/)
+2. **API Key** - Use `--api-key <key>` for single operations
+3. **Environment Variable** - Set `APERTODNS_API_KEY`
+
+## JSON Output
 
-## Cron Setup
+All commands support `--json` flag for machine-readable output:
 
 ```bash
-# Every 5 minutes
-*/5 * * * * apertodns --cron
+# Get domains as JSON
+apertodns --domains --json
+
+# Get your IP as JSON
+apertodns --my-ip --json
+
+# Combine with API key for scripting
+apertodns --api-key ak_xxx... --domains --json
 ```
 
+## Daemon Mode
+
+Run continuously to keep your DNS updated:
+
+```bash
+# Default interval (5 minutes)
+apertodns --daemon
+
+# Custom interval (60 seconds)
+apertodns --daemon --interval 60
+```
+
+## Automatic Updates (Cron)
+
+Set up automatic IP updates with cron:
+
+```bash
+# Update every 5 minutes
+*/5 * * * * /usr/local/bin/apertodns --cron >> /var/log/apertodns.log 2>&1
+
+# Or every minute for faster updates
+* * * * * /usr/local/bin/apertodns --cron
+```
+
+Find your apertodns path with: `which apertodns`
+
+## Router Integration (DynDNS2)
+
+ApertoDNS is compatible with routers that support DynDNS2 protocol:
+
+```
+Server: api.apertodns.com
+Protocol: DynDNS2
+Path: /nic/update
+Username: your-token
+Password: your-token
+Hostname: yourdomain.apertodns.com
+```
+
+### Compatible Devices
+
+- **Routers**: ASUS, TP-Link, Netgear, Ubiquiti, pfSense, OPNsense, DD-WRT, OpenWRT
+- **NAS**: Synology DSM, QNAP QTS, TrueNAS
+- **Other**: Any device supporting DynDNS2/DynDNS protocol
+
+## Configuration Storage
+
+Configuration is stored in platform-specific locations:
+
+- **Linux**: `~/.config/apertodns/` or `~/.apertodns/`
+- **macOS**: `~/.config/apertodns/`
+- **Windows**: `%APPDATA%\apertodns\`
+
+## Security
+
+- Credentials are stored locally, never transmitted except to ApertoDNS servers
+- API keys support granular scopes for least-privilege access
+- All API communication uses HTTPS
+- No cross-account data access - strict user isolation
+
+## Examples
+
+```bash
+# Quick status check
+apertodns --status
+
+# Test DNS propagation
+apertodns --test myserver.apertodns.com
+
+# Create domain and get token
+apertodns --add-domain newserver.apertodns.com
+
+# List domains as JSON
+apertodns --domains --json
+
+# Use API key for automation
+APERTODNS_API_KEY=ak_xxx... apertodns --domains --json
+```
+
+## Links
+
+- **Website**: [apertodns.com](https://apertodns.com)
+- **Dashboard**: [apertodns.com/dashboard](https://apertodns.com/dashboard)
+- **Documentation**: [apertodns.com/docs](https://apertodns.com/docs)
+- **Issues**: [GitHub Issues](https://github.com/1r0n3d3v3l0per/apertodns/issues)
+
+## Support
+
+Need help?
+- Open an issue on [GitHub](https://github.com/1r0n3d3v3l0per/apertodns/issues)
+- Email: support@apertodns.com
+
 ## License
 
-MIT - Aperto Network
+MIT - [Aperto Network](https://apertodns.com)