Referencia de la CLI

Además de install y uninstall (consulta Instalar Vision), el binario vision envuelve el resto de la operación diaria: iniciar y detener el servicio, comprobar su estado, hacer copias de seguridad y restaurar datos, e inspeccionar la configuración. Cada comando es un envoltorio delgado y honesto: la mayoría imprime el comando systemctl o journalctl subyacente que ejecuta (en stderr, para que el stdout canalizado se mantenga limpio), y esos comandos directos siguen plenamente soportados si prefieres usarlos tal cual.

Ejecuta vision help para ver la lista completa, o vision help <command> para el detalle de un comando.

Servicio

Comando	Qué hace
vision start [--force]	Valida la configuración y luego ejecuta systemctl start vision.
vision stop	systemctl stop vision.
vision restart [--force]	Valida la configuración y luego ejecuta systemctl restart vision.
vision enable [--now]	systemctl enable [--now] vision: iniciar en el arranque.
vision disable [--now]	systemctl disable [--now] vision.
vision logs [-f] [-n N] [--since W] [--until W] [-o FMT]	journalctl -u vision --no-pager, con tus opciones. -f sigue la salida.

La compuerta de validación

start y restart ejecutan exactamente la misma validación que el servicio ejecuta al arrancar (con los secretos de /etc/vision/vision.env superpuestos igual que los aplica systemd) y se niegan a continuar mostrando el error real si la configuración no es válida. Reiniciar con una configuración que no arranca es una de las formas más comunes de dejar un sitio caído; --force omite la compuerta si necesitas continuar de todos modos.

vision logs nunca necesita root: la lectura del journal funciona para los miembros del grupo systemd-journal (o adm). Si no ves entradas, agrega tu usuario a ese grupo o ejecútalo con sudo.

Diagnósticos

Comando	Qué muestra
vision status [--json] [--verbose]	El estado de la unidad, las mismas comprobaciones que ejecuta /readyz, las rutas y tamaños de configuración y datos, y dos advertencias de desfase: un binario que fue reemplazado sin reiniciar, y archivos auxiliares WAL propiedad de root en los que el servicio no puede escribir. Una línea License muestra el ID público del archivo de licencia, o not activated (el estado en vivo y la caducidad están en Settings → License).
vision doctor [--json] [--config PATH] [--db PATH]	Un chequeo sin conexión para una máquina donde el servicio no arranca: validación de la configuración, comprobaciones de esquema/entorno/keyring, forma de la unidad de systemd, una comprobación de integridad de la base de datos y de la versión del esquema, propiedad de archivos, espacio libre en disco, el conjunto efectivo de workers habilitados, los parámetros de seguridad del barrido de reconciliación, el archivo de licencia (existe, propietario vision, modo 0600, concedido por la unidad) y si los servidores de licencias responden (solo advertencia; consulta Licencias). Cada hallazgo viene acompañado de una solución.
vision version	Imprime la versión del binario y la hora de compilación.

Tanto status como doctor funcionan sin root: las comprobaciones que requieren root se muestran como omitidas en lugar de fallar. status nunca termina con 0 mientras el servicio está caído, por lo que es seguro usarlo en scripts de monitorización:

Código de salida	Significado
0	ok
4	no instalado
5	unidad no activa
6	activo, pero no listo

En una instalación nueva, status informa Not ready: no Alta server yet con la dirección de Settings → Connections: agrega un servidor y pasa a estar listo.

Datos

Comando	Qué hace
vision backup [--output PATH|-] [--no-secrets] [--no-maps] [--force] [--recover-wal] [--db PATH] [--config PATH]	Copia de seguridad en caliente consistente, sin tiempo de inactividad. Consulta Copia de seguridad y restauración.
vision restore <archive> [--dry-run] [--stop-service] [--yes] [--force-key-mismatch]	Restauración verificada y protegida. --yes acepta en scripts la confirmación específica del host. Consulta Copia de seguridad y restauración.
vision reset-password <email> [--url BASE] [--config PATH] [--db PATH]	Genera un enlace de restablecimiento de contraseña de un solo uso para un administrador bloqueado. Consulta Recuperar una contraseña olvidada.

Configuración

Comando	Qué hace
vision config validate [--config PATH] [--env-file PATH]	Comprueba la configuración instalada exactamente como lo haría el arranque: la misma combinación de config.yaml y el archivo env de systemd.
vision config print [--format text|json]	Imprime la configuración efectiva y combinada con todos los secretos ocultos: es seguro pegarla en un ticket de soporte.
vision config print --reference	Imprime la configuración de referencia completa y anotada (cada clave, su valor por defecto y una descripción): no requiere una configuración instalada.

Ningún subcomando de config necesita root.

Puesta en marcha

Comando	Qué hace
vision install [--no-restart]	Instala o actualiza el servicio sin reemplazar la configuración ni los secretos. Un binario modificado reinicia un servicio activo a menos que se indique --no-restart.
vision uninstall	Elimina el servicio pero conserva la configuración y los datos.
vision uninstall --purge [--yes] [--no-backup]	También elimina la configuración, los datos, el usuario del sistema y el binario. Hace una copia de seguridad final y requiere la confirmación purge <hostname>; --yes es para scripts. Evita --no-backup a menos que los datos sean desechables.

Códigos de salida

Código	Significado
0	éxito
1	intentado y fallido
2	error de uso
3	precondición no cumplida: no es Linux, no hay systemctl, o requiere root
4	no instalado (no se encontró unidad, configuración ni base de datos)
5 / 6	solo status: consulta la tabla anterior

Política de root

• Los comandos que modifican (start, stop, restart, enable, disable, install, uninstall, restore) comprueban ellos mismos si se ejecutan como root y se niegan a continuar con el código de salida 3 en lugar de dejar que systemctl caiga en un aviso de polkit, que se quedaría colgado para siempre sin terminal (cron, CI, una tubería).
• Los comandos de solo lectura (status, logs, config, doctor) nunca requieren root; degradan filas o comprobaciones individuales en su lugar.

Cambiar el nivel de registro

El nivel de registro se fija en el arranque: deliberadamente no hay un interruptor en tiempo de ejecución. Defínelo en el archivo env y reinicia:

echo 'VISION_LOG_LEVEL=debug' | sudo tee -a /etc/vision/vision.env
sudo vision restart

Recuerda quitarlo después: debug es muy verboso.

Tamaño del journal

Los registros del servicio son JSON estructurado en stdout, que termina en journald: la rotación de registros es tarea de journald, no de Vision. Si vision logs muestra que el journal consume espacio en disco, limítalo en /etc/systemd/journald.conf:

[Journal]
SystemMaxUse=1G

y luego sudo systemctl restart systemd-journald.

Actualización

Vuelve a ejecutar el instalador con el nuevo binario: es idempotente (la configuración y los secretos nunca se sobrescriben) y reinicia el servicio una vez que el binario realmente ha cambiado:

curl -fsSL https://vision.cesbo.com/install.sh | sh

Para una ventana de mantenimiento controlada, ejecuta el binario recién descargado sin reiniciar y aplícalo cuando estés listo:

sudo /path/to/new/vision install --no-restart
sudo vision restart

vision install también reinicia un servicio que todavía ejecuta una copia más antigua del binario: el comando de una línea mueve primero el nuevo binario a su lugar. vision status advierte si el proceso en ejecución es anterior al binario en disco.

Proxy inverso / TLS

El binario no tiene un listener TLS por diseño: en producción, TLS se termina en un proxy inverso delante de él. Un sitio nginx mínimo:

server {
    listen 443 ssl;
    server_name vms.example.com;
    ssl_certificate     /etc/letsencrypt/live/vms.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/vms.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3303;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # SSE (alerts/status feeds) and long-lived requests:
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

o Caddy, que gestiona los certificados automáticamente:

vms.example.com {
    reverse_proxy 127.0.0.1:3303 {
        flush_interval -1
    }
}

Luego, en /etc/vision/config.yaml, agrega el origen público a http.allowed_origins, define http.secure_cookies: true y ejecuta sudo vision restart. Si además defines http.internal_addr para un listener separado de métricas/salud, no apuntes la comprobación de salud del propio proxy a /readyz en el listener público: consulta la nota que imprime vision status.