@davinti/vitruvio-cli (1.7.1)

Published 2026-08-05 19:04:40 +00:00 by tiago.inaba

Set up this registry in your project .npmrc file:

@davinti:registry=https://git.davinti.com.br/api/packages/davinTI/npm/

To install the package using npm, run the following command:

npm install @davinti/vitruvio-cli@1.7.1

or add it to the package.json file:

"@davinti/vitruvio-cli": "1.7.1"

For more information on the npm registry, see the documentation.

CLI tooling for Vitruvio content repositories

vitruvio-cli

Ferramentas de linha de comando para criação e manutenção de repositórios Vitruvio.

Pré-requisitos

Node.js 18 ou superior
Git instalado e acessível no terminal
Chave SSH configurada no servidor Gitea da davinTI (necessária para clonar via SSH — há fallback automático para HTTPS)

Instalação

Linux

# 1. Clone o repositório
git clone ssh://git@git.davinti.com.br:2222/davinTI/vitruvio-cli.git
cd vitruvio-cli

# 2. Instale as dependências
npm install

# 3. Registre o comando globalmente
npm link

Se você usa mise para gerenciar versões do Node, rode também:

mise reshim

Verifique a instalação:

vitruvio --help

Windows

Abra o PowerShell ou Prompt de Comando como administrador.

# 1. Clone o repositório
git clone ssh://git@git.davinti.com.br:2222/davinTI/vitruvio-cli.git
cd vitruvio-cli

# 2. Instale as dependências
npm install

# 3. Registre o comando globalmente
npm link

Verifique a instalação:

vitruvio --help

Nota: Caso o terminal não reconheça o comando vitruvio após o npm link, verifique se o diretório de binários globais do npm está no PATH do sistema. Para descobrir o caminho:
npm config get prefix
Adicione o caminho retornado (ex: C:\Users\SeuUsuario\AppData\Roaming\npm) nas variáveis de ambiente do sistema em Painel de Controle → Sistema → Variáveis de Ambiente → Path.

Comandos

`vitruvio init <nome>`

Cria um novo repositório Vitruvio a partir do template base.

vitruvio init meu-modulo

Clona o template projeto-base para um diretório com o nome informado
Remove o histórico git do template e inicializa um repositório limpo sem remotes
Pronto para você adicionar seu próprio remote e fazer o primeiro commit

Após o init:

cd meu-modulo

# Edite o vitruvio.json com a chave e nome do seu módulo
# Depois:
git remote add origin <url-do-seu-repositório>
git add .
git commit -m "feat: scaffold inicial"

`vitruvio update-repo`

Atualiza os arquivos CLAUDE.md gerenciados no repositório atual com a versão mais recente do template.

# Execute dentro de um repositório Vitruvio (onde há vitruvio.json)
cd meu-modulo
vitruvio update-repo

Arquivos atualizados por este comando:

CLAUDE.md
endpoints/CLAUDE.md
panels/CLAUDE.md
patches/CLAUDE.md
processes/CLAUDE.md
queries/CLAUDE.md
reports/CLAUDE.md
scripts/CLAUDE.md

Nenhum outro arquivo do repositório é tocado.

`vitruvio docs`

Abre a documentação Java do Vitruvio no navegador padrão.

vitruvio docs

Abre o arquivo docs/java/index.html do diretório de plataforma. Caso os arquivos não existam, o comando orienta a executar vitruvio update-base primeiro.

`vitruvio update-base`

Sincroniza os diretórios gerenciados do diretório de plataforma local com o repositório base-claude.

vitruvio update-base

Diretório de plataforma atualizado:

Sistema	Caminho
Linux	`~/.local/share/vitruvio-platform/`
Windows	`%LOCALAPPDATA%\vitruvio-platform\`

Diretórios gerenciados (substituídos completamente):

libs/
docs/
examples/

Qualquer outro diretório ou arquivo fora dessa lista não é alterado.

`vitruvio mcp`

Gerencia servidores MCP (Model Context Protocol) no .mcp.json do repositório atual.

vitruvio mcp          # sem argumento: mostra o uso
vitruvio mcp help     # mesma coisa (vitruvio mcp help add mostra a ajuda só do "add")
vitruvio mcp list     # lista os MCPs disponíveis, em ordem alfabética
vitruvio mcp add      # cadastra um novo MCP no catálogo, localmente (interativo)
vitruvio mcp push     # envia (commit + push) as alterações locais pendentes pro Gitea
vitruvio mcp <nome>   # adiciona ou atualiza esse MCP no .mcp.json (raiz do repositório atual)
vitruvio update mcp   # atualiza (URL + headersHelper) todos os MCPs já listados no .mcp.json do repositório atual

vitruvio mcp add pergunta nome (chave), descrição e URL, valida o formato (nome em letras minúsculas/números/hífen, URL bem-formada, sem colidir com um subcomando existente) e grava direto em src/data/mcps.json — só localmente, nesta instalação. Também aceita um modo não-interativo, sem prompts, informando as três flags:

vitruvio mcp add --nome sacolao2 --descricao "Sacolão 2" --url http://sacolao2.vproxy.lan:8000/mcp
vitruvio mcp add --nome sacolao2 --descricao "..." --url "..." --force  # sobrescreve se já existir

Restrito ao time Infra da organização davinTI no Gitea — mesma restrição para add, push e o comando de remoção (não listado no --help, ver CLAUDE.md). Antes de fazer qualquer coisa, o comando confirma (via API do Gitea, usando o token de vitruvio token) que o dono do token pertence a esse time; caso contrário, recusa com uma mensagem explicando a restrição. Sem token do Gitea configurado, orienta a rodar vitruvio token primeiro.

add/a remoção só gravam localmente — dá pra fazer vários de uma vez (adicionar, remover, ajustar) antes de mandar pro repositório. vitruvio mcp push envia todas as alterações locais pendentes juntas, num commit só, com uma mensagem resumindo o que mudou (+adicionados, ~alterados, -removidos). Funciona de qualquer instalação, em qualquer diretório: se essa instalação for um checkout git de verdade (ex.: via npm link, o fluxo de dev), usa git add/commit/push local, mantendo o histórico com sua autoria normal; em qualquer outra instalação (npm install -g/vitruvio update cli, sem .git nenhum ali), usa a API de conteúdo do Gitea pra escrever o arquivo direto no main, sem precisar de checkout — o commit ali aparece com o dono do token configurado (vitruvio token) como autor. Se der erro (sem rede, sem permissão, token sem acesso ao repo etc.), as alterações continuam salvas só localmente nesta instalação.

Catálogo lido em tempo real, sem precisar publicar uma nova versão do CLI. mcp list, mcp add, mcp push e mcp <nome> sempre começam buscando src/data/mcps.json direto do repositório vitruvio-cli no Gitea (branch main), usando o token de vitruvio token. Assim que o mcp push cai no repo, qualquer instalação do vitruvio já enxerga as entradas novas na próxima vez que rodar um desses comandos — sem precisar de npm publish nem de vitruvio update cli. O resultado é salvo em cache (~/.vitruvio/mcps-cache.json); se a busca remota falhar (sem rede, sem token, timeout), o comando cai pro cache mais recente e, na ausência de cache, pro catálogo empacotado nesta instalação — nunca quebra por falta de conexão. Havendo alterações locais pendentes (ainda sem mcp push), esse refresh é pulado — as entradas recém-salvas continuam aparecendo até você decidir enviar ou descartar (git checkout -- src/data/mcps.json num checkout de dev).

Cada entrada gerada usa headersHelper em vez de gravar o token direto no arquivo:

"liderban": {
  "type": "http",
  "url": "http://liderban.vproxy.lan:8000/mcp",
  "headersHelper": "node \"/home/<usuário>/.vitruvio/mcp-gitea-auth-header.js\""
}

(no Windows, o mesmo caminho vira algo como node "C:\\Users\\<usuário>\\.vitruvio\\mcp-gitea-auth-header.js")

Detecção de nvm: se a máquina usa nvm (Linux/macOS), o headersHelper gerado é diferente:

"headersHelper": "NODE_VERSION=default \"/home/<usuário>/.nvm/nvm-exec\" node \"/home/<usuário>/.vitruvio/mcp-gitea-auth-header.js\""

Isso existe porque o Claude Code roda o headersHelper num shell não-interativo, que não sourcinga nvm.sh — então o node do nvm (que só existe num path versionado, ~/.nvm/versions/node/vX.Y.Z/bin/node) não está no PATH desse shell, e o helper falharia silenciosamente (a conexão aparenta "authenticated" no handshake, mas toda tool call cai em "requires re-authorization"). nvm-exec tem path fixo e resolve a versão certa em tempo de execução, então funciona independente do PATH do shell que o disparou. Sem nvm detectado (NVM_DIR/~/.nvm/nvm-exec ausentes) ou no Windows, o comando volta a ser só node "<caminho>".

O catálogo de MCPs disponíveis (nome, descrição, URL) vive em src/data/mcps.json — não contém segredos.
A autenticação reaproveita o mesmo token pessoal do Gitea configurado via vitruvio token. O token nunca é escrito no .mcp.json: vitruvio mcp <nome> garante que ~/.vitruvio/mcp-gitea-auth-header.js existe (sincronizado a partir do template em src/data/mcp-gitea-auth-header.js) e aponta headersHelper pra node "<esse-arquivo>", que lê ~/.vitruvio/config.json em tempo de execução e imprime o header Authorization: token <PAT>. Sem token do Gitea salvo, vitruvio mcp <nome> orienta a rodar vitruvio token primeiro.
O helper é em Node.js (não bash/python) de propósito: é o único runtime que o próprio vitruvio-cli já exige em Windows e Linux/macOS, e o Claude Code executa headersHelper dentro de um shell (cmd.exe no Windows, sh/bash no Linux/macOS) — node "<caminho>" funciona igual nos dois.
vitruvio mcp <nome> grava (ou atualiza, se a chave já existir) apenas a entrada mcpServers.<nome> do .mcp.json, preservando qualquer outra entrada já presente no arquivo.
vitruvio update mcp percorre as entradas já presentes em mcpServers e garante que as que existem no catálogo apontam pro helper mais recente; não toca em entradas que não pertencem ao catálogo (ex.: um MCP configurado manualmente). Sem .mcp.json no diretório atual, o comando avisa e não faz nada. Também roda automaticamente dentro de vitruvio update (sem alvo) quando há um .mcp.json no diretório.

Dependencies

ID	Version
commander	^12.0.0
fs-extra	^11.2.0

Details

npm

2026-08-05 19:04:40 +00:00

55 KiB

Assets (1)

vitruvio-cli-1.7.1.tgz 55 KiB

Versions (38) View all

1.10.0

2026-10-05

1.9.1

2026-09-29

1.9.0

2026-09-29

1.8.0

2026-09-25

1.7.3

2026-09-18