nx9-url-shortener/docs/CLI.md

BZOD Command Line Interface (CLI)

BZOD includes a comprehensive command-line interface for server administration, backups, migrations, diagnostics, validation, and multi-user management.

The current command list for BZOD v0.8.0 is:

$ bzod --help

BZOD - Personal Redirector & Landing Page Platform

Usage: bzod <COMMAND>

Commands:
  serve           Start the BZOD web server
  backup          Create a tar.gz backup of all databases
  restore         Restore databases from a tar.gz backup file
  migrate         Apply pending database schema migrations
  stats           Print database statistics and record counts in the terminal
  validate        Perform a one-shot validation of all registered short link destinations
  create-admin    Create a new administrator user in the database
  doctor          Run database diagnostics and health checks
  shorten         Shorten a URL (Feature 3)
  expand          Expand a shortened code or custom slug to its destination URL (Feature 4)
  create-user     Create a new standard user in the database
  delete-user     Delete a standard user and all their databases/slugs
  disable-user    Disable a standard user
  enable-user     Enable a standard user
  reset-password  Reset standard user's password
  list-users      List all standard/system users
  backup-user     Backup a standard user's databases to a .tar.zst package
  restore-user    Restore a standard user's databases from a .tar.zst package
  admin-migrate   FUTURE: Migrate legacy admin content to a specific admin tenant database
  repair          Repair registry and database inconsistencies
  help            Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

---

Server Operations

Start Web Server

bzod serve

---

Backup & Recovery

Full Backup

bzod backup

Creates a compressed backup archive containing:

• users.db
• system.db
• content databases
• analytics databases
• user directories

Full Restore

bzod restore backup.tar.gz

Restores an entire BZOD installation from a backup archive.

---

Database Operations

Apply Migrations

bzod migrate

Applies any pending database migrations.

Safe to execute multiple times.

Database Statistics

bzod stats

Displays database statistics, record counts, storage usage, and operational metrics.

---

Validation & Diagnostics

Validate Links

bzod validate

Checks all registered URLs and reports invalid destinations.

Health Diagnostics

bzod doctor

Performs:

• SQLite integrity checks
• WAL validation
• Database availability checks
• Storage verification
• System health diagnostics
• Global registry integrity validation

Registry Repair

bzod repair registry --dry-run

Provides a transaction-safe repair utility for fixing global slug registry inconsistencies detected by bzod doctor.

• Use --dry-run to preview changes safely.
• Use --force to execute changes and remove orphaned entries.
• Use --slug <slug> to target a single missing entry.

---

URL Management

Create Short URL

bzod shorten https://example.com

Expand Existing URL

bzod expand abc123

Returns the destination URL associated with the slug.

---

Administrator Management

Create Administrator

bzod create-admin admin

Creates a new administrator account.

---

User Management

List Users

bzod list-users

Displays all users in the platform.

Create User

bzod create-user alice

Creates a new standard user.

Disable User

bzod disable-user alice

Blocks login and invalidates sessions.

Enable User

bzod enable-user alice

Re-enables a disabled user.

Reset Password

bzod reset-password alice

Resets a user's password.

Delete User

bzod delete-user alice

Deletes:

• User account
• User databases
• Sessions
• API tokens
• Slug ownership

---

User Backup Operations

Backup User

bzod backup-user alice

Creates a portable .tar.zst archive containing all user-owned data.

Restore User

bzod restore-user alice.tar.zst

Restores a user from a previously generated archive.

---

Recommended Maintenance

Daily:

bzod doctor

Weekly:

bzod backup

Before Upgrades:

bzod backup
bzod validate

After Upgrades:

bzod migrate
bzod doctor

---

Related Documentation

• INSTALL.md
• MULTI_USER.md
• ADMIN_GUIDE.md
• BACKUP_RESTORE.md
• SECURITY.md
• API.md
• ARCHITECTURE.md

---

Data Directory Configuration

BZOD requires an explicit physical data directory root. There is no implicit ./data fallback.

Configuration Precedence

1. CLI --data-dir (Highest priority)

   bzod serve --data-dir /var/lib/bzod/data
   bzod migrate --data-dir=/var/lib/bzod/data --dry-run
   

2. Environment Variable NX9_BZOD_DATA_DIR

   export NX9_BZOD_DATA_DIR=/var/lib/bzod/data
   bzod serve
   

3. Configuration File (bzod.toml / config.toml)

   data_dir = "/var/lib/bzod/data"
   

4. Error: If no data directory is provided via CLI, NX9_BZOD_DATA_DIR, or config file, BZOD terminates with an actionable error.