Skip to content

management-cli.mdx

Latest commit

 

History

History
135 lines (97 loc) · 4.02 KB

management-cli.mdx

File metadata and controls

135 lines (97 loc) · 4.02 KB
Raw
title Management CLI
description Manage your self-hosted Nixopus instance from the command line.

After installation, the nixopus command is available at /usr/local/bin/nixopus. All commands require root.

sudo nixopus status

Commands

Command Description
nixopus status Show service health
nixopus logs [service] Tail logs
nixopus update Pull latest images and restart
nixopus restart [service] Restart all or a specific service
nixopus stop Stop all services
nixopus config Show current configuration
nixopus config set KEY=VALUE Update a config value (restart required)
nixopus domain add <domain> [flags] Switch to domain-based HTTPS
nixopus domain remove Switch back to IP-based HTTP
nixopus ip set [flags] <ip> Change host IP
nixopus port set <http|https|ssh> <port> Change a port
nixopus backup Backup database and config
nixopus admin-bootstrap [email] [password] Create the initial admin via the auth API
nixopus uninstall Remove containers (keeps data)
nixopus uninstall --purge Remove everything including data

Services

When a command accepts a [service] argument, use one of:

  • nixopus-api
  • nixopus-auth
  • nixopus-view
  • nixopus-caddy
  • nixopus-agent
  • nixopus-db
  • nixopus-redis

Examples

Check service health

nixopus status

Tail logs for a specific service

nixopus logs nixopus-api

Change the domain

Ensure DNS is configured before running this.

nixopus domain add panel.example.com

Domain flags

Flag Description
--ipv4 Use IPv4 (A record). This is the default.
--ipv6 Use IPv6 (AAAA record).
--verify=auto|strict|off DNS verification mode (default auto). auto warns on mismatch but proceeds. strict aborts on mismatch. off skips verification entirely (use when behind Cloudflare or a proxy).

The --ipv4/--ipv6 flag overrides the instance-level IP_FAMILY for this command only. When omitted, the configured IP_FAMILY is used.

# Add domain with IPv6
nixopus domain add panel.example.com --ipv6

# Add domain behind Cloudflare proxy (skip DNS check)
nixopus domain add panel.example.com --verify=off

# Strict verification — abort if DNS doesn't match
nixopus domain add panel.example.com --verify=strict

Switch back to IP mode

nixopus domain remove

Change host IP

# Set IPv4 (default)
nixopus ip set 93.184.216.34

# Set IPv6 explicitly
nixopus ip set --ipv6 2001:db8::1

# Auto-detected: addresses containing ":" are treated as IPv6
nixopus ip set 2001:db8::1

When setting an IPv6 address while IP_FAMILY is still ipv4, the CLI prints a hint to enable dual-stack with nixopus config set IP_FAMILY=dual.

Update a config value

nixopus config set LOG_LEVEL=info
nixopus restart

Admin bootstrap

nixopus admin-bootstrap creates the first admin account by calling Better Auth's POST /api/auth/sign-up/email through Caddy. Use it when the install-time bootstrap was skipped (no ADMIN_EMAIL set), failed (auth service slow to start, origin mismatch), or when you want to recreate the admin from the values stored in .env.

sudo nixopus admin-bootstrap

By default it uses ADMIN_EMAIL and ADMIN_PASSWORD from /opt/nixopus/.env. You can override one or both inline:

sudo nixopus admin-bootstrap admin@example.com 'NewPass!23'

Behavior:

  • Returns immediately with a success message if the admin already exists (USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL from the auth service).
  • Prints the auth service's code field on validation failures (PASSWORD_TOO_SHORT, INVALID_ORIGIN, EMAIL_PASSWORD_SIGN_UP_DISABLED, etc.).
  • Polls for up to ADMIN_BOOTSTRAP_TIMEOUT seconds (default 30 for the CLI, 60 during install) so the auth service has time to come up.

The password must satisfy the auth service rules.