Referência da CLI

Além de install e uninstall (veja Instalar o Vision), o binário vision encapsula o restante da operação do dia a dia: iniciar e parar o serviço, verificar sua saúde, fazer backup e restaurar dados e inspecionar a configuração. Cada comando é um wrapper fino e transparente — a maioria imprime o comando systemctl ou journalctl subjacente que executa (em stderr, para que a stdout redirecionada por pipe permaneça limpa), e esses comandos brutos continuam totalmente suportados se você preferir usá-los diretamente.

Execute vision help para a lista completa, ou vision help <command> para o detalhe de um comando.

Serviço

Comando	O que faz
vision start [--force]	Valida a configuração e depois executa systemctl start vision.
vision stop	systemctl stop vision.
vision restart [--force]	Valida a configuração e depois executa systemctl restart vision.
vision enable [--now]	systemctl enable [--now] vision — iniciar no boot.
vision disable [--now]	systemctl disable [--now] vision.
vision logs [-f] [-n N] [--since W] [--until W] [-o FMT]	journalctl -u vision --no-pager, com as suas flags. -f acompanha.

A barreira de validação

start e restart executam exatamente a validação que o serviço executa no boot — com os segredos de /etc/vision/vision.env sobrepostos da mesma forma que o systemd os aplica — e recusam com o erro real se a configuração for inválida. Reiniciar com uma configuração que falha no boot é uma das formas mais comuns de derrubar um site; --force ignora a barreira caso você precise seguir em frente mesmo assim.

vision logs nunca precisa de root: a leitura do journal funciona para membros do grupo systemd-journal (ou adm). Se você não vir nenhuma entrada, adicione o seu usuário a esse grupo ou execute-o com sudo.

Diagnósticos

Comando	O que mostra
vision status [--json] [--verbose]	Estado da unit, as mesmas verificações que /readyz executa, caminhos e tamanhos de configuração/dados e dois avisos de divergência: um binário que foi substituído sem reinício e arquivos auxiliares WAL pertencentes ao root nos quais o serviço não consegue gravar. Uma linha License mostra o ID público do arquivo de licença, ou not activated (o estado em tempo real e a expiração estão em Settings → License).
vision doctor [--json] [--config PATH] [--db PATH]	Um check-up offline para uma máquina em que o serviço não inicia: validação da configuração, verificações de esquema/ambiente/keyring, formato da unit do systemd, uma verificação de integridade do banco de dados e da versão do esquema, propriedade dos arquivos, espaço livre em disco, o conjunto efetivo de workers habilitados, as configurações de segurança da varredura de reconciliação, o arquivo de licença (existe, proprietário vision, modo 0600, concedido pela unit) e se os servidores de licença respondem (apenas aviso — veja Licenciamento). Cada achado vem acompanhado de uma correção.
vision version	Imprime a versão do binário e a hora da compilação.

Tanto status quanto doctor funcionam sem root — as verificações exclusivas de root são mostradas como ignoradas em vez de falhar. status nunca sai com 0 enquanto o serviço está parado, então é seguro usá-lo em scripts de monitoramento:

Código de saída	Significado
0	ok
4	não instalado
5	unit não ativa
6	ativa, mas não pronta

Em uma instalação nova, status informa Not ready: no Alta server yet com o endereço de Settings → Connections — adicione um servidor e ele passa a ficar pronto.

Dados

Comando	O que faz
vision backup [--output PATH|-] [--no-secrets] [--no-maps] [--force] [--recover-wal] [--db PATH] [--config PATH]	Backup a quente consistente — sem tempo de inatividade. Veja Backup e restauração.
vision restore <archive> [--dry-run] [--stop-service] [--yes] [--force-key-mismatch]	Restauração verificada e protegida. --yes aceita o prompt específico do host em scripts. Veja Backup e restauração.
vision reset-password <email> [--url BASE] [--config PATH] [--db PATH]	Gera um link de redefinição de senha de uso único para um administrador bloqueado. Veja Recuperar uma senha esquecida.

Configuração

Comando	O que faz
vision config validate [--config PATH] [--env-file PATH]	Verifica a configuração instalada exatamente como o boot faria — a mesma combinação de config.yaml e do arquivo de ambiente do systemd.
vision config print [--format text|json]	Imprime a configuração efetiva e combinada com todos os segredos ocultados — seguro para colar em um ticket de suporte.
vision config print --reference	Imprime a configuração de referência completa e anotada (cada chave, seu padrão e uma descrição) — não precisa de configuração instalada.

Nenhum dos subcomandos de config precisa de root.

Configuração inicial

Comando	O que faz
vision install [--no-restart]	Instala ou atualiza o serviço sem substituir a configuração ou os segredos. Um binário alterado reinicia um serviço ativo, a menos que --no-restart esteja definido.
vision uninstall	Remove o serviço, mas mantém a configuração e os dados.
vision uninstall --purge [--yes] [--no-backup]	Também exclui a configuração, os dados, o usuário do sistema e o binário. Faz um backup final e exige a confirmação purge <hostname>; --yes é para scripts. Evite --no-backup, a menos que os dados sejam descartáveis.

Códigos de saída

Código	Significado
0	sucesso
1	tentou e falhou
2	erro de uso
3	pré-condição não atendida — não é Linux, sem systemctl ou precisa de root
4	não instalado (nenhuma unit, configuração ou banco de dados encontrado)
5 / 6	somente status — veja a tabela acima

Política de root

• Comandos que alteram o sistema (start, stop, restart, enable, disable, install, uninstall, restore) verificam por conta própria se há root e recusam com saída 3, em vez de deixar o systemctl cair em um prompt do polkit — que travaria para sempre sem um terminal (cron, CI, um pipe).
• Comandos somente leitura (status, logs, config, doctor) nunca exigem root; em vez disso, eles degradam linhas ou verificações individuais.

Alterando o nível de log

O nível de log é fixado no boot — deliberadamente não há alternância em tempo de execução. Defina-o no arquivo env e reinicie:

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

Lembre-se de removê-lo depois — debug é verboso.

Dimensionamento do journal

Os logs do serviço são JSON estruturado na stdout, que vai para o journald — a rotação de logs é tarefa do journald, não do Vision. Se vision logs mostrar o journal consumindo espaço em disco, limite-o em /etc/systemd/journald.conf:

[Journal]
SystemMaxUse=1G

depois execute sudo systemctl restart systemd-journald.

Atualizando

Execute o instalador novamente com o novo binário — ele é idempotente (a configuração e os segredos nunca são sobrescritos) e reinicia o serviço quando o binário realmente mudou:

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

Para uma janela de manutenção controlada, execute o binário recém-baixado sem reiniciar e aplique-o quando estiver pronto:

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

vision install também reinicia um serviço que ainda executa uma cópia mais antiga do binário — o one-liner move o novo binário para o lugar primeiro. vision status avisa se o processo em execução é anterior ao binário em disco.

Proxy reverso / TLS

O binário não tem listener TLS por design — em produção, o TLS é terminado em um proxy reverso na frente dele. Um site 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;
    }
}

ou Caddy, que cuida dos certificados automaticamente:

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

Depois, em /etc/vision/config.yaml, adicione a origem pública a http.allowed_origins, defina http.secure_cookies: true e execute sudo vision restart. Se você também definir http.internal_addr para um listener separado de métricas/saúde, não aponte a verificação de saúde do próprio proxy para /readyz no listener público — veja a nota impressa por vision status.