@davinti/vitruvio-cli (1.8.0)
Installation
@davinti:registry=https://git.davinti.com.br/api/packages/davinTI/npm/npm install @davinti/vitruvio-cli@1.8.0"@davinti/vitruvio-cli": "1.8.0"About this package
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
vitruvioapós onpm link, verifique se o diretório de binários globais do npm está no PATH do sistema. Para descobrir o caminho:npm config get prefixAdicione 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-basepara 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 update mcp # atualiza (URL + header de auth) 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 grava um header Authorization estático, igual para todos os MCPs e
para todo dev (não é mais por dev nem via headersHelper):
"liderban": {
"type": "http",
"url": "http://liderban.vproxy.lan:8000/mcp",
"headers": { "Authorization": "token <token único do catálogo>" }
}
- 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 usa um único token, igual pra todos os MCPs e todos os devs — embutido no próprio
vitruvio-cli(constanteMCP_AUTH_HEADERSemsrc/utils/mcp.js), não depende devitruvio tokennem de nenhuma configuração local. Como o token vai direto no.mcp.json,vitruvio mcp <nome>/vitruvio update mcpgarantem automaticamente uma linha.mcp.jsonno.gitignoredo repositório atual — não commite esse arquivo. vitruvio mcp <nome>grava (ou atualiza, se a chave já existir) apenas a entradamcpServers.<nome>do.mcp.json, preservando qualquer outra entrada já presente no arquivo.vitruvio update mcppercorre as entradas já presentes emmcpServerse garante que as que existem no catálogo apontam pro header de autenticação mais recente; não toca em entradas que não pertencem ao catálogo (ex.: um MCP configurado manualmente). Sem.mcp.jsonno diretório atual, o comando avisa e não faz nada. Também roda automaticamente dentro devitruvio update(sem alvo) quando há um.mcp.jsonno diretório.
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
--detalhesrecebe um arquivo.md(convertido para HTML pelo CLI) ou.html(enviado como está). O servidor sanitiza o HTML (lista fechada de tags;img,style,scriptetc. são removidos).- O criador é o login de
vitruvio login. --area(emcriarebuscar) 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) oualta(ou0,1,2).- Mostra um preview e pede confirmação;
--yespula a confirmação e--dry-runsó 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 |