Referência da CLI

O MangoStudio é distribuído como um binário único que também funciona como CLI para rodar e gerenciar um servidor local. Os mesmos comandos funcionam no binário instalado (mangostudio) e a partir do código-fonte (bun run apps/api/src/index.ts <command>).

🇺🇸 English version

Canais de instalação

Escolha qualquer canal de distribuição — cada um entrega o mesmo binário pré-compilado e sidecar do frontend. Veja a matriz de instalação do README ou:

Comandos

Ações de service: install, uninstall, status, start, stop, restart. install grava uma unidade de usuário — unidade systemd mangostudio.service no Linux, agente launchd com.mangostudio.hub no macOS, Tarefa Agendada MangoStudio Hub no Windows — que roda serve e registra a saída em ~/.mango/logs/service.log.

env install/env update espelham o fluxo de instalação da página Environments a partir do terminal: exigem installs_enabled = true em config.toml (ou MANGO_ENV_INSTALLS_ENABLED=true), aceitam --environment por paridade com a API — mas por enquanto sempre recusado, pois a CLI não tem sessão para checar o allowInstalls de um ambiente pareado — e --version para receitas que aceitam uma versão do Node. Saem com 0 em sucesso, 1 se a execução terminar em qualquer status diferente de succeeded, e 2 quando a receita nunca chega a rodar (bloqueada, não suportada, faltando um pré-requisito, ou somente-cópia).

upgrade descobre primeiro quem instalou o binário (marcador do launcher npm/Cargo, depois o install-origin.json na raiz de versões, depois o caminho do executável) e só então age. Numa instalação feita pelos scripts, o hub resolve o alvo, baixa e verifica o arquivo (SHA256SUMS, ou o dist.integrity do npm para um commit canary), e executa o script de instalação embutido no seu próprio binário com --local; o script move o ponteiro current, grava install-origin.json com origin: upgrade e limpa versões antigas. Depois um hub em execução é reiniciado pelo ponteiro current. Numa instalação por gerenciador de pacotes (npm/bun/pnpm, Homebrew, Scoop, Cargo) o comando do gerenciador é impresso, ou executado com --yes no macOS e Linux; no Windows --yes entrega o comando a um processo que espera este sair. Homebrew e Scoop são somente stable; container e checkout de código-fonte são recusados com o comando a usar. Sem --yes, um terminal interativo confirma antes de baixar e antes de reiniciar; fora de um terminal, upgrade só relata o que existe e sai com 0. Códigos de saída: 0 atualizado, já atual ou --check; 1 recusado; 2 falha de download, verificação ou do script. A verificação diária de release nova ([updates] no config.toml, MANGO_UPDATES_CHECK, NO_UPDATE_NOTIFIER, DO_NOT_TRACK, CI) alimenta as linhas Installed via e Update de status e doctor e o aviso na página “Esta máquina”. Detalhes na versão em inglês.

setup

O primeiro comando de uma instalação nova, e a metade em terminal do fluxo de primeira execução do navegador. Garante que existe um segredo de autenticação, opcionalmente instala o serviço em segundo plano, inicia o hub (ou reaproveita um já em execução) e abre o endereço no navegador.

• --service / --no-service respondem a pergunta do serviço de antemão. Sem um terminal para perguntar, um deles é obrigatório: instalar uma unidade sobrevive ao comando, e pular silenciosamente deixaria uma instalação automatizada com um hub que morre no logout enquanto reporta sucesso.
• --no-open imprime a URL em vez de abrir qualquer coisa.
• Onde nenhum navegador pode ser aberto — uma sessão Linux sem DISPLAY, tipicamente por SSH — a URL e uma linha ssh -L são impressas em vez de uma afirmação de que uma janela apareceu.
• Um hub que já responde ao health check é reaproveitado, nunca reiniciado. Um que está vivo mas ainda não responde — subindo, ou falhando o /health por um instante — é esperado em vez de substituído, e se ele morrer durante a espera, um substituto é iniciado. Um arquivo de estado deixado por um que travou é limpo antes.
• Sai com código diferente de zero se o hub que ele iniciou não responder em 30 segundos, e nomeia o pid quando quem ficou calado foi o que já estava rodando.

setup não consegue conectar uma CLI de fornecedor, escolher um repositório ou enviar a primeira mensagem; isso é do fluxo no navegador, e ele diz isso abrindo o fluxo em vez de alegar que estão prontos. Veja docs/pt-br/guides/first-run.md.

Exemplos

mangostudio setup              # instalação nova: segredo, serviço, início, abrir
mangostudio setup --no-service --no-open  # automatizado, imprime a URL
mangostudio serve              # foreground em localhost:3001
mangostudio serve 3000         # foreground em localhost:3000
mangostudio serve 127.0.0.1 -d # background em 127.0.0.1:3001
mangostudio serve lan:3000 -d  # background em 0.0.0.0:3000
mangostudio service install    # inicia agora e a cada login
mangostudio restart            # reinicia do jeito que foi iniciado
mangostudio logs -f            # acompanha o log do servidor
mangostudio --version
mangostudio status
mangostudio stop

Para detalhes de service (o que a unidade roda, a lista de variáveis de ambiente permitidas, a passagem de bastão na instalação, linger no Linux), restart, logs, modo background, instância única, arquivos de runtime, códigos de saída, a seção Doctor e configuração, consulte a versão completa em inglês.

O hub inicia o Local como o binário mangostudio-runtime. mangostudio doctor reporta o binário que o Local executaria — MANGOSTUDIO_RUNTIME_BINARY, o binário ao lado de um hub standalone ou o build cargo mais recente de um checkout do código-fonte — e marca a linha como falha quando ele está ausente, já que o Local não inicia sem ele: reinstale o MangoStudio (ou defina MANGOSTUDIO_RUNTIME_BINARY) ou, em um checkout, execute cargo build -p mangostudio-runtime. Uma versão diferente da do hub é só um aviso — o handshake recusa a divergência, então reinstale em vez de misturar releases — e não é reportada contra um hub de desenvolvimento, que não tem release para comparar.

O segundo binário, mangostudio-runtime, tem os próprios comandos — connect, serve, setup, install, service, health, doctor e audit. install copia o binário que você baixou para dentro do slot (~/.mango/runtime/<slot>/) e publica o lançador usado por service install. No Unix, é o ponteiro current; no Windows, é o arquivo estável mangostudio-runtime.cmd, que aponta para um executável de versão imutável e dispensa elevação, Modo de Desenvolvedor e privilégio para links simbólicos. A Tarefa Agendada MangoStudio Runtime reinicia o lançador após o código de saída 75. Um connect ou serve iniciado à mão a partir do slot também sai com o código 75 depois de uma atualização ao vivo pelo hub, e nada o reinicia: execute o mesmo comando de novo para usar a nova versão, ou instale o serviço para que a atualização o reinicie sozinha. service stop e restart aguardam a instalação ativa terminar, com limite total de 30 segundos; service stop --force pula essa espera. No Windows, a parada encerra também qualquer runtime que tenha sobrado do slot desta home, e encerra o runtime imediatamente: diferente do systemd e do launchd, uma etapa de instalação em andamento é interrompida junto. A credencial guardada é restrita ao seu usuário — por modo 0600 no POSIX e por ACL (icacls) no Windows, onde chmod só altera o atributo somente-leitura. Detalhes na versão em inglês.