davinTI
Repositories
6
 Projects Packages

@davinti/vitruvio-cli (1.9.0)

Published 2026-09-29 19:29:21 +00:00 by jonatha.correa

Installation

@davinti:registry=https://git.davinti.com.br/api/packages/davinTI/npm/
npm install @davinti/vitruvio-cli@1.9.0
"@davinti/vitruvio-cli": "1.9.0"

About this package

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. Veja também o tutorial passo a passo.

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 mcp login    # login no Keycloak pelo navegador — uma vez, vale para todos os MCPs
vitruvio mcp status   # quem está logado (--check confirma a sessão no Keycloak)
vitruvio mcp logout   # revoga a sessão no Keycloak e apaga o token local
vitruvio update mcp   # atualiza (URL + autenticação) 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, mcp <nome> e update mcp 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).

Autenticação

Todos os MCPs do catálogo autenticam com login no Keycloak (realm davinti). A entrada gerada não tem segredo nenhum: aponta para um helper local compartilhado, com o OAuth nativo do Claude Code como fallback:

"lab-davinti": {
  "type": "http",
  "url": "http://lab.vproxy.lan:8000/mcp",
  "headersHelper": "NODE_VERSION=default \"/home/voce/.nvm/nvm-exec\" node \"/home/voce/.vitruvio/mcp-auth-header.js\"",
  "oauth": { "clientId": "quantum-mirage-cli", "callbackPort": 33418 }
}

Rode vitruvio mcp login uma vez: o navegador abre, você entra com o SSO, e o mesmo login vale para todos os MCPs. O helper (~/.vitruvio/mcp-auth-header.js, instalado/atualizado por mcp login, mcp <nome> e update mcp) guarda o refresh token em ~/.vitruvio/mcp-oauth.json (permissão 600) e renova o access token sozinho — a sessão dura enquanto os MCPs forem usados pelo menos uma vez a cada 30 dias. Quando ela expira (ou é revogada), o helper abre o navegador sozinho na próxima vez que o Claude Code conectar; depois de logar, /mcp → Reconnect ou reinicie a sessão. Numa máquina sem navegador (SSH), rode vitruvio mcp login à mão: ele imprime a URL. Logs do helper (nunca com token) ficam em ~/.vitruvio/mcp-auth.log.

O .mcp.json é específico da máquina (o headersHelper tem caminhos absolutos), então vitruvio mcp <nome>/vitruvio update mcp garantem automaticamente uma linha .mcp.json no .gitignore do repositório atual — não commite esse arquivo. Depois de gerar ou alterar entradas, o Claude Code pede para aprovar os servers de novo na próxima abertura.

  • O catálogo de MCPs disponíveis (nome, descrição, URL) vive em src/data/mcps.json — não contém segredos.
  • 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 busca o catálogo mais recente no Gitea, percorre as entradas já presentes em mcpServers e regrava as que existem no catálogo com a URL e a autenticação atuais (e instala/atualiza o helper do Keycloak, avisando se falta vitruvio mcp login); 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.

vitruvio doctor

Diagnostica problemas do ambiente e diz, para cada um, o que fazer. Com --fix, corrige o que for seguro corrigir (sempre com backup). Hoje cobre a área mcp; outras áreas entram no mesmo comando.

vitruvio doctor                   # todas as áreas, só diagnóstico (não altera nada)
vitruvio doctor mcp               # só MCPs — rode dentro do repositório com .mcp.json
vitruvio doctor mcp lab-davinti   # só um MCP do catálogo
vitruvio doctor mcp --fix         # diagnostica e corrige (feche o Claude Code antes)
vitruvio doctor mcp -v            # mostra também as verificações que passaram
vitruvio doctor mcp --json        # saída para anexar num chamado (nunca inclui tokens)

Cada verificação sai como ok, aviso, erro ou info; o código de saída é 1 se sobrar algum erro.

MCP não conecta? Rode vitruvio doctor mcp antes de chamar alguém. Ele verifica:

  • Cache de login do Claude Code: entradas "travadas" de MCPs do catálogo (sintoma: o Claude Code não abre o login e o log do server mostra 401 em /authorize). O --fix remove só essas entradas, com backup, e só com o Claude Code fechado (--force pula essa checagem). Linux/Windows: ~/.claude/.credentials.json; macOS: Keychain.
  • Keycloak alcançável.
  • Helper e login: helper instalado e atualizado, arquivo de token e permissão 600, e o helper rodado como o Claude Code roda (mede o tempo; não abre o navegador).
  • Cada server do .mcp.json: DNS (VPN), conexão (3 tentativas — falha parcial indica problema no vproxy), OAuth ligado, URL pública e issuer conferem com o catálogo, token aceito, entrada no formato atual.

O --fix também reinstala o helper, ajusta a permissão do token, apaga o helper antigo e regrava entradas desatualizadas do .mcp.json. Problemas do lado do servidor (URL divergente, server sem OAuth, 503) não têm correção local: a saída manda avisar a infra.

vitruvio kb

Consulta e inclui tópicos na Base de Conhecimento do Vitruvio (endpoint base-conhecimento). Pensado para uso por skills do Claude Code: buscar contexto durante o desenvolvimento e documentar o que foi aprendido. A API não edita nem exclui — corrigir ou apagar um tópico é só pelo painel Cadastro de Base de Conhecimento.

vitruvio kb areas                              # lista as áreas (nome ou id vão no "--area")
vitruvio kb buscar recebimento nf              # todos os termos precisam casar (título, descrição, área, conteúdo)
vitruvio kb buscar nf --area suporte --limite 50  # restringe a uma área (nome ou id); limite padrão 20, máximo 50
vitruvio kb ler 33                             # tópico completo (conteúdo em texto + anexos)
vitruvio kb criar --titulo "Como o recebimento gera a NF" --descricao "Resumo do fluxo" \
  --area desenvolvimento --prioridade media --detalhes topico.md --referencia "ticket 23917"

areas, buscar, ver e criar aceitam --json (saída só em JSON no stdout, para ferramentas). No ver --json, o campo detalhes vem em HTML, como a API devolve.

kb criar

  • --detalhes recebe um arquivo .md (convertido para HTML pelo CLI) ou .html (enviado como está). O servidor sanitiza o HTML (lista fechada de tags; img, style, script etc. são removidos).
  • O criador é o login de vitruvio login.
  • --area (em criar e buscar) aceita o id ou o nome da área, sem diferenciar maiúsculas nem acentos (gestao = GESTÃO). Um trecho do nome também serve se casar com uma área só; se casar com mais de uma, o comando lista as opções.
  • --prioridade: baixa, media (padrão) ou alta (ou 0, 1, 2).
  • Mostra um preview e pede confirmação; --yes pula a confirmação e --dry-run só mostra o payload. Sem terminal interativo (ex.: rodado por uma ferramenta), exige --yes.
  • Título repetido na mesma área não é erro: o comando informa o id do tópico existente e sai com sucesso (--json → { "id": 33, "duplicado": true }). Assim, repetir após um timeout não duplica.
  • O tópico só fica disponível para a IA depois da próxima execução do agendamento IA_integracao.

Ambiente e token

A API ainda só existe no Lab, que é o ambiente padrão. Cada ambiente tem um token próprio do endpoint base-conhecimento (não é o token de vitruvio ws-token), então o token é salvo por ambiente em ~/.vitruvio/config.json.

vitruvio kb host                 # mostra o ambiente atual e se há token para ele
vitruvio kb host producao        # troca o padrão ("lab", "producao" ou um endereço, ex.: http://localhost:8080)
vitruvio kb host --padrao        # volta ao padrão do CLI
vitruvio kb token                # salva o token do ambiente atual (interativo)
vitruvio kb buscar nf --host lab # usa outro ambiente só nesta chamada

Prioridade do ambiente: --host → variável VITRUVIO_KB_HOST → vitruvio kb host → padrão do CLI (Lab). O token também pode vir da variável VITRUVIO_KB_TOKEN, que tem prioridade sobre o salvo. Quando a API chegar à produção, basta trocar DEFAULT_KB_HOST em src/utils/kb.js. Quem nunca rodou kb host passa a usar produção automaticamente.

Dependencies

Dependencies

ID Version
commander ^12.0.0
fs-extra ^11.2.0
marked ^15.0.12
Details
npm
2026-09-29 19:29:21 +00:00
0
100 KiB
Assets (1)
vitruvio-cli-1.9.0.tgz 100 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