@davinti/vitruvio-cli (1.6.5)

Published 2026-08-03 20:38:27 +00:00 by jonatha.correa

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.6.5

or add it to the package.json file:

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

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 list   # lista os MCPs disponíveis
vitruvio mcp add    # cadastra um novo MCP no catálogo (interativo)
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 "list"/"add") e grava direto em src/data/mcps.json. 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
vitruvio mcp add --nome sacolao2 --descricao "..." --url "..." --push  # já commita e envia (push)

Restrito ao time Infra da organização davinTI no Gitea. Antes de perguntar qualquer coisa (ou de aplicar as flags), 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.

Depois de salvar (interativo, pergunta; via flag, só com --push), commita e envia (push) o src/data/mcps.json pro repositório do vitruvio-cli — 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. Recusando o push (ou não passando --push), ou se der erro (sem rede, sem permissão, token sem acesso ao repo etc.), a entrada continua salva só localmente nesta instalação.

Catálogo lido em tempo real, sem precisar publicar uma nova versão do CLI. mcp list, mcp add 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 push do mcp add cai no repo, qualquer instalação do vitruvio já enxerga a entrada nova 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. Numa instalação em checkout git com alterações locais pendentes em src/data/mcps.json (um mcp add ainda não commitado/enviado), esse refresh é pulado — a entrada recém-salva continua aparecendo até você decidir commitar/enviar ou descartar.

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-03 20:38:27 +00:00

54 KiB

Assets (1)

vitruvio-cli-1.6.5.tgz 54 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