PVS CLI - A ferramenta CLI da Prevent Senior

O PVS-CLI é uma ferramenta de linha de comando que permite a execução de comandos de forma automatizada, facilitando a execução de tarefas repetitivas e a manutenção de ambientes de desenvolvimento.

Pré-requisitos

• Instale o Node.js (versão 18 ou superior) que inclui o NPM (gerenciador de pacotes do Node.js).

Instalação

Instale o PVS-CLI globalmente com o npm:

npm install -g @preventsenior/pvs-cli

Auto-Update

O PVS-CLI verifica automaticamente se há uma nova versão disponível (uma vez por dia). Quando uma atualização é detectada:

1. Notificação: Você será informado sobre a nova versão
2. Pergunta: O CLI perguntará se deseja atualizar agora
3. Atualização automática: Se você aceitar, a atualização será feita automaticamente
4. Fallback manual: Se houver erro de permissão, o CLI mostrará o comando manual

Opções:

• ✅ Aceitar (padrão): Atualiza automaticamente e você roda o comando novamente
• ❌ Recusar: Continua com a versão atual (pode atualizar depois)
• ⏭️ Cancelar (Ctrl+C): Cancela e continua com a versão atual

Nota sobre permissões:

• Windows: Pode ser necessário abrir o terminal como Administrador
• Linux/macOS: Pode ser necessário usar sudo para instalações globais

Desabilitar verificação: A verificação automática ocorre apenas uma vez por dia para não interromper o fluxo de trabalho.

Comandos disponíveis

• adicionar-modulo
• login-aws
• assumir-role
• login-ca-aws
• login-docker
• boundary-config
• boundary
• download-artifact-backend
• upload-artifact-backend
• infra-create
• editar-values
• gravity-adicionar-api
• gravity-adicionar-api-consumida

Documentação

• Comando adicionar-modulo:

  pvs adicionar-modulo

  Esse comando deve ser rodado na raiz do projeto que deseja adicionar um módulo, esse projeto deve conter a árvore de diretórios criados pelo Gravity da Prevent. Ele irá adicionar um ou mais módulos ao projeto, seguindo o padrão de módulos da Prevent Senior. Você pode adicionar o parâmetro --modulo ou -m para passar o(s) nome(s) do(s) módulo(s) diretamente, separados por vírgula, sem precisar de interação.

  pvs adicionar-modulo --modulo database
  -------
  pvs adicionar-modulo -m database,kafka

  Você pode adicionar o parâmetro --sem-exemplo ou -s para remover os arquivos de exemplo do módulo gerado.

  pvs adicionar-modulo --sem-exemplo
  -------
  pvs adicionar-modulo -s

  Você pode adicionar o parâmetro --git-add ou -g para que esses módulos sejam adicionados ao git.

  pvs adicionar-modulo --git-add
  -------
  pvs adicionar-modulo -g

• Comando login-aws:

  Pré-requisitos:

  • aws-cli instalado e configurado.

  pvs login-aws

  Esse comando pode ser rodado em qualquer diretório. Ele irá fazer login na AWS via SSO com base no profile definido no arquivo ~/.aws/config. Não se preocupe se você tiver mais de um profile configurado, serão todos listados para que você selecione qual deseja se autenticar. Ao final da autenticação lhe será perguntado se quer se autenticar no CodeArtifact com NPM ou Maven (Para facilitar sua vida 😁). Você pode adicionar o parâmetro --all-login-ca ou -a para logar no Maven e NPM com CodeArtifact.

  pvs login-aws --all-login-ca
  -------
  pvs login-aws -a

  Você pode adicionar o parâmetro --profile-default ou -pd para executar com o profile default da AWS.

  pvs login-aws --profile-default
  -------
  pvs login-aws -pd

  Caso você não tenha configurado o profile no arquivo ~/.aws/config para login via SSO, você pode adicioná-lo com o comando abaixo:

  aws configure sso

  Após rodar o comando acima, você será solicitado a informar o SSO URL, SSO Region, SSO Account ID, SSO Role Name e SSO Start URL. Após informar esses dados, você terá um profile mais ou menos assim:

  [profile Developer]
  sso_session = SessionDeveloper
  sso_account_id = 000000000000
  sso_role_name = Developer
  region = sa-east-1
  output = json
    
  [sso-session SessionDeveloper]
  sso_start_url = https://sso-da-sua-empresa/start#/
  sso_region = sa-east-1
  sso_registration_scopes = sso:account:access

• Comando assumir-role:

  Pré-requisitos:

  • aws-cli instalado e configurado.

  pvs assumir-role

  Esse comando deve ser rodado no diretório raiz do projeto que queira assumir a role. Será assumida uma role padrão para apps da Prevent Senior.

  Ex: arn:aws:iam::000000000000:role/app/${env}-${app_name} | arn:aws:iam::000000000000:role/app/dev-pvs-cli. Essa role é criada (quando solicitado) para o seu app com as permissões necessárias.

  Você pode adicionar o parâmetro --add-profile ou -p para que o comando adicione ou atualize o profile e suas credências nos arquivos: ~/.aws/config e ~/.aws/credentials.

  pvs assumir-role --add-profile
  -------
  pvs assumir-role -p

  Por padrão a role que será assumida é a de dev, mas você pode adicionar o parâmetro --staging ou -s para assumir a role de homologação.

  pvs assumir-role --staging
  -------
  pvs assumir-role -s

  Você pode adicionar o parâmetro --wildfly ou -w para assumir a role para wildfly no Argo.

  pvs assumir-role --wildfly
  -------
  pvs assumir-role -w

  Você pode adicionar o parâmetro --profile-default ou -pd para executar com o profile default da AWS.

  pvs assumir-role --profile-default
  -------
  pvs assumir-role -pd

• Comando login-ca-aws:

  Pré-requisitos:

  • aws-cli instalado e configurado.

  pvs login-ca-aws

  Esse comando pode ser rodado em qualquer diretório. Ele irá fazer a autenticação no CodeArtifact da AWS com base no profile selecionado. Você posse adicionar o parâmetro --npm ou -n para que o login seja feito somente com NPM.

  pvs login-ca-aws --npm
  -------
  pvs login-ca-aws -n

  Ou adicionar o parâmetro --maven ou -m para que o login seja feito somente com Maven.

  pvs login-ca-aws --maven
  -------
  pvs login-ca-aws -m

  Você pode adicionar o parâmetro --profile-default ou -pd para executar com o profile default da AWS.

  pvs login-ca-aws --profile-default
  -------
  pvs login-ca-aws -pd

  Ao omitir os parâmetros de tipo (npm/maven), o login será feito com NPM e Maven.

• Comando login-docker:

  Pré-requisitos:

  • aws-cli instalado e configurado.
  • docker instalado e configurado.

  pvs login-docker

  Esse comando pode ser rodado em qualquer diretório. Ele irá fazer login no Docker apontando para o ERC com base no profile selecionado. Você pode adicionar o parâmetro --profile-default ou -pd para executar com o profile default da AWS.

  pvs login-docker --profile-default
  -------
  pvs login-docker -pd

Comandos adicionados na versão 1.1.0

• Comando boundary-config:

  Este comando sempre irá forçar um novo login no boundary, lembre-se de estar autenticado com sua conta a_{cpf} no navegador

  Pré-requisitos:

  • boundary na versão 0.16.0 ou superior instalado.

  pvs boundary-config

  Esse comando pode ser rodado em qualquer diretório. Ele irá criar um arquivo de configuração para o boundary, deixando sempre um squad e um ambiente para acesso rápido. Você pode usar o parâmetro --show-config ou -s visualizar o arquivo de configuração.

  pvs boundary-config --show-config
  -------
  pvs boundary-config -s

  Você pode adicionar o parâmetro --squad ou -T para informar o squad.

  pvs boundary-config --squad <squad_name>
  -------
  pvs boundary-config -T <squad_name>

  Você pode adicionar o parâmetro --environment ou -E para informar o ambiente, as opções são [dev,hom,prd].

  pvs boundary-config --environment <environment_name>
  -------
  pvs boundary-config -E <environment_name>

  Ao omitir os parâmetros, será listado as squads que você tem permissão para selecionar, e posteriormente o ambiente.

  

• Comando boundary:

  Pré-requisitos:

  • boundary na versão 0.16.0 ou superior instalado.
  • pvs boundary-config executado ou --force-login | -f informado junto para logar pela primeira vez.

  pvs boundary

  Esse comando pode ser rodado em qualquer diretório. pvs boundary é um comando para facilitar sua conexão a um host. Se configurado com pvs boundary-config ele irá listar os hosts disponíveis para conexão. Você pode adicionar o parâmetro --squad ou -T para informar a squad, o comando irá ignorar a configuração feita com o pv boundary-config, e irá lhe perguntar em qual ambiente deseja listar os hosts.

  pvs boundary --squad <squad_name>
  -------
  pvs boundary -T <squad_name>

  Você pode adicionar o parâmetro --force-login ou -f para que o comando force um novo login no boundary.

  pvs boundary --force-login
  -------
  pvs boundary -f

Comandos adicionados na versão 1.2.0

• Comando download-artifact-backend

  Pré-requisitos:

  • aws-cli instalado e configurado.
  • pvs login-aws executado.

  pvs download-artifact-backend <artifact_name> <artifact_version>

  Esse comando pode ser rodado em qualquer diretório (Mas lembre-se, o artefato será baixado no diretório que o comando rodar). pvs download-artifact-backend é um comando para facilitar o download de um artefato .war ou .jar do CodeArtifact. Os parâmetros <artifact_name> e <artifact_version> são obrigatórios, e você deve informar o nome do artefato e a versão que deseja baixar. Você pode adicionar o parâmetro --snapshot ou -s para informar que o artefato encontra-se no repositório snapshots do CodeArtifact.

  pvs download-artifact-backend portalweb-impl 1.0.0-SNAPSHOT --snapshot
  -------
  pvs download-artifact-backend portalweb-impl 1.0.0-SNAPSHOT -s

  Você pode adicionar o parâmetro --type ou -t para informar o tipo do artefato, pode ser war ou jar, por padrão, ao não informar o parâmetro, o tipo será war.

  pvs download-artifact-backend portalweb-impl 1.0.0 --type jar
  -------
  pvs download-artifact-backend portalweb-impl 1.0.0 -t jar

  Você pode adicionar o parâmetro --profile-default ou -pd para executar com o profile default da AWS.

  pvs download-artifact-backend portalweb-impl 1.0.0 --profile-default
  -------
  pvs download-artifact-backend portalweb-impl 1.0.0 -pd

• Comando upload-artifact-backend

  Pré-requisitos:

  • aws-cli instalado e configurado.
  • Maven instalado e configurado.
  • pvs login-ca-aws executado (necessário estar logado no CodeArtifact com Maven).

  pvs upload-artifact-backend

  Esse comando pode ser rodado em qualquer diretório. pvs upload-artifact-backend é um comando para facilitar o upload de um artefato .war ou .jar para o CodeArtifact. O comando aceita os seguintes parâmetros opcionais. Se não informados, serão solicitados interativamente:

  Você pode adicionar o parâmetro --file ou -f para informar o caminho do arquivo para upload.

  pvs upload-artifact-backend --file ./target/meu-app.war
  -------
  pvs upload-artifact-backend -f ./target/meu-app.war

  Você pode adicionar o parâmetro --groupId ou -g para informar o groupId do artefato.

  pvs upload-artifact-backend --groupId br.com.preventsenior
  -------
  pvs upload-artifact-backend -g br.com.preventsenior

  Você pode adicionar o parâmetro --artifactId ou -a para informar o artifactId do artefato.

  pvs upload-artifact-backend --artifactId meu-app-impl
  -------
  pvs upload-artifact-backend -a meu-app-impl

  Você pode adicionar o parâmetro --artifactVersion ou -av para informar a versão do artefato.

  pvs upload-artifact-backend --artifactVersion 1.0.0
  -------
  pvs upload-artifact-backend -av 1.0.0

  Você pode adicionar o parâmetro --packaging ou -p para informar o tipo de pacote (jar ou war).

  pvs upload-artifact-backend --packaging war
  -------
  pvs upload-artifact-backend -p war

  Exemplo completo com todos os parâmetros:

  pvs upload-artifact-backend -f ./target/meu-app.war -g br.com.preventsenior -a meu-app-impl -av 1.0.0 -p war

Comandos adicionados na versão 1.4.0

• Comando infra-create

  Pré-requisitos:

  • Projeto TerraForm v3 clonado em sua maquina.
  • Git instalado e configurado para fazer commit e criar PR.

  pvs infra-create

  Esse comando deve ser rodado no diretório do projeto terraform-v3. Ao rodar o comando, será perguntado o nome do projeto, o ambiente, o nome do squad e o nome do componente. Com essas informações, o comando irá criar um diretório com o nome do projeto, ambiente e squad, e dentro desse diretório, será criado um arquivo api_key_${project_name}.tf com o conteúdo padrão para criação de uma infraestrutura da api-key. Será criado também um arquivo chamado header.tf com o conteúdo padrão para criação de um header caso ainda não exista para o projeto.

• Comando editar-values

  Pré-requisitos:

  • Projeto deve conter arquivos values-{env}.yaml (dev, hom ou prd).

  pvs editar-values

  Esse comando deve ser rodado no diretório do projeto que contém os arquivos values-{env}.yaml. O comando permite editar interativamente o arquivo values-{env}.yaml através de um menu guiado. Primeiro, você seleciona o ambiente (dev, hom ou prd), depois escolhe as áreas que deseja editar (como database, kafka, redis, etc.). Funcionalidades:

  • Seleção do ambiente (dev, hom, prd)
  • Edição guiada por menus interativos
  • Validação de valores durante a edição
  • Revisão de alterações antes de salvar
  • Opção de salvar ou descartar alterações Este comando facilita a edição dos arquivos de configuração sem precisar editar manualmente o YAML, reduzindo erros de sintaxe e formatação.

Comandos Gravity

• Comando gravity-adicionar-api

  Pré-requisitos:

  • Git instalado e configurado.
  • Projeto Maven com módulo main.
  • Branch main limpa (sem alterações pendentes).
  • Projeto deve ter a propriedade pvs.squad.name definida no application.properties do módulo main.

  pvs gravity-adicionar-api

  Este comando deve ser executado na raiz do projeto e na branch main. O comando cria automaticamente o arquivo api-info.yaml do Gravity e registra a API no Gravity. Ele realiza as seguintes ações:

  1. Valida se o projeto possui o módulo main
  2. Busca o nome da squad no application.properties
  3. Gera o arquivo api-info.yaml com as informações da API
  4. Adiciona a API ao arquivo catalog-info.yaml
  5. Realiza commit e push das alterações
  6. Registra a API no Gravity automaticamente
  7. Executa refresh no Gravity Importante: O comando verifica se você está na branch main e se não há alterações pendentes antes de executar.

• Comando gravity-adicionar-api-consumida

  Pré-requisitos:

  • Git instalado e configurado.
  • Projeto deve possuir arquivo catalog-info.yaml.
  • Branch main limpa (sem alterações pendentes).
  • Conectado à VPN (para acessar o Gravity).

  pvs gravity-adicionar-api-consumida

  Este comando deve ser executado na raiz do projeto e na branch main. O comando permite adicionar APIs consumidas pelo seu projeto no arquivo catalog-info.yaml. Ele realiza as seguintes ações:

  1. Busca todas as APIs disponíveis no Gravity
  2. Filtra APIs que já estão registradas como consumidas
  3. Apresenta um menu de seleção múltipla para escolher as APIs
  4. Adiciona as APIs selecionadas ao catalog-info.yaml
  5. Realiza commit e push das alterações
  6. Executa refresh no Gravity Importante: O comando verifica se você está na branch main e se não há alterações pendentes antes de executar.

Configuração Automática do Claude Code

O PVS-CLI configura o Claude Code automaticamente se ele estiver instalado. Não é necessário fazer nada!

O que é configurado:

1. MCP Servers: Adiciona servidores MCP (como pvs-doc-framework-spring e taskmaster-ai) ao arquivo ~/.claude.json, permitindo que o Claude acesse:

   • Documentação oficial do framework Spring da Prevent Senior
   • Ferramentas de gerenciamento de tarefas (TaskMaster AI)

2. Permissões: Configura permissões no arquivo ~/.claude/settings.json, incluindo:

   • Permissões para comandos bash específicos do PVS CLI
   • Permissões para ferramentas MCP do framework Spring
   • Modo padrão de aceitação de edições
   • Bloqueio de comandos perigosos e arquivos sensíveis

Quando ocorre a configuração:

• ✅ Na instalação do CLI (npm install -g @preventsenior/pvs-cli)
• ✅ Antes de qualquer comando ser executado (atualização automática e silenciosa)

Requisito:

• Claude Code deve estar instalado no sistema

Nota: A configuração é totalmente automática e silenciosa. Se o Claude Code não estiver instalado, a configuração é ignorada sem erros.

Autocomplete Automático

O PVS-CLI instala o autocomplete automaticamente na primeira execução de qualquer comando. Não é necessário fazer nada!

Se precisar gerenciar manualmente o autocomplete (casos especiais), existe um comando oculto completion:

pvs completion install   # Forçar reinstalação
pvs completion uninstall # Desinstalar
pvs completion fix       # Reparar problemas

Como funciona a instalação automática:

Na primeira vez que você executar qualquer comando do PVS-CLI, o autocomplete será automaticamente configurado no seu shell (.bashrc ou .zshrc). O comando adiciona apenas uma linha no início do seu arquivo de configuração do shell:

source <(pvs completion script)

Isso carrega o script de autocomplete dinamicamente, mantendo seus arquivos de configuração limpos e atualizados automaticamente. A linha é adicionada no início do arquivo para garantir carregamento prioritário.

Compatibilidade:

✅ Ambientes Suportados:

• Windows Git Bash
• Windows WSL (Bash/Zsh)
• Linux (Bash/Zsh)
• macOS (Bash/Zsh)

❌ Ambientes NÃO Suportados:

• Windows CMD (Prompt de Comando)
• Windows PowerShell

Nota: Se você usa CMD ou PowerShell no Windows, instale o Git Bash para ter suporte ao autocomplete.

Ativar o autocomplete imediatamente (SEM reiniciar o terminal):

eval "$(pvs completion activate)"

Este comando aplica as configurações no shell atual instantaneamente! ⚡

Ou use a forma tradicional:

Recarregue o seu shell manualmente:

source ~/.bashrc  # Para Bash
-------
source ~/.zshrc   # Para Zsh

Ou simplesmente reinicie o terminal.

Com o autocomplete instalado, você pode pressionar TAB para autocompletar comandos e opções do PVS-CLI:

pvs <TAB>                      # Lista todos os comandos
pvs adicionar-<TAB>            # Autocompleta para "adicionar-modulo"
pvs adicionar-modulo <TAB>     # Lista todas as opções do comando

Comandos adicionais do completion (uso avançado):

Ativar imediatamente após instalação:

eval "$(pvs completion activate)"

Este é o comando recomendado para ativar o autocomplete sem reiniciar o terminal!

Ver o script de completion:

pvs completion script

Reparar problemas de configuração:

pvs completion fix

Use este comando se tiver erros no bash (como "binary operator expected"). Ele remove configurações antigas problemáticas e permite uma reinstalação limpa.

Desinstalar o autocomplete:

pvs completion uninstall

Perguntas Frequentes (FAQ):

P: O autocomplete não funciona no meu Windows. O que fazer? R: Certifique-se de estar usando o Git Bash, não o CMD ou PowerShell. O autocomplete bash não funciona em CMD/PowerShell nativos.

P: Preciso instalar o autocomplete manualmente? R: Não! A partir da versão 2.3.0, o autocomplete é instalado automaticamente na primeira execução de qualquer comando.

P: Como ativar o autocomplete sem reiniciar o terminal? R: Execute: eval "$(pvs completion activate)" - isso ativa imediatamente no shell atual!

P: Funciona no macOS Catalina ou superior? R: Sim! O CLI detecta automaticamente que o macOS Catalina+ usa zsh por padrão e configura o arquivo .zshrc corretamente.

P: Funciona no WSL (Windows Subsystem for Linux)? R: Sim! O WSL usa Linux nativo, então bash/zsh completion funciona perfeitamente.

P: Como verificar se o autocomplete está instalado? R: Verifique se o arquivo ~/.bashrc (ou ~/.zshrc) contém a linha: source <(pvs completion script)

Obrigado por usar o PVS-CLI! 🚀

Se tiver alguma dúvida ou sugestão, entre em contato com time Sculptor, ficaremos felizes em ajudar! 😁