DEV Community

Cover image for Como instalar o CLI Apidog com um agente de IA para programação
Lucas
Lucas

Posted on • Originally published at apidog.com

Como instalar o CLI Apidog com um agente de IA para programação

Você já tem um agente de codificação de IA capaz de editar arquivos, executar testes e ler a saída do terminal. Em vez de instalar manualmente o Apidog CLI copiando comandos npm de uma aba para outra, delegue a instalação ao agente e verifique cada etapa pelo terminal.

Experimente o Apidog hoje

O Apidog CLI é um pacote npm chamado apidog-cli. Ele executa, a partir do terminal, os cenários de teste de API que você criou no Apidog. O fluxo é simples: verificar Node.js, instalar o CLI, autenticar com token e executar um primeiro cenário.

Neste guia, você vai usar um agente como Claude Code, Cursor, Windsurf ou GitHub Copilot em modo agente para fazer a parte mecânica. Você fornece prompts objetivos, o agente executa os comandos e você valida a saída.

Por que delegar a instalação ao agente

O comando de instalação não muda:

npm install -g apidog-cli@latest
Enter fullscreen mode Exit fullscreen mode

A diferença é que o agente pode:

  1. Executar comandos no shell.
  2. Ler erros como command not found, permissões ou problemas de PATH.
  3. Adaptar a próxima ação ao ambiente real da máquina.
  4. Verificar versões e autenticação sem você supervisionar cada linha.

Você continua responsável por validar os pontos críticos: versão instalada, autenticação e código de saída dos testes.

Pré-requisitos

Antes de começar, confirme que você tem:

  1. Node.js e npm instalados

    O apidog-cli é distribuído via npm e executa no Node.js. Use uma versão LTS atual.

  2. Conta Apidog com acesso a pelo menos um projeto

    O CLI executa cenários existentes na sua conta Apidog.

  3. Um cenário de teste salvo no Apidog

    O executor roda cenários, não requisições isoladas. Crie um cenário no app Apidog com requisições encadeadas e asserções. Se precisar revisar asserções, veja Asserções de API: um guia prático.

  4. Um agente com permissão para executar comandos shell

    Claude Code, Cursor Agent, Windsurf Cascade e GitHub Copilot Agent Mode funcionam, desde que possam executar comandos, não apenas sugeri-los.

Passo 1: peça ao agente para verificar Node.js e npm

Use um prompt explícito:

Verifique se o Node.js e o npm estão instalados nesta máquina. Execute node -v e npm -v e me diga as versões. Se um deles estiver faltando, me diga, não tente instalar o Node você mesmo.

O agente deve executar:

node -v
npm -v
Enter fullscreen mode Exit fullscreen mode

Verificando versões do Node.js e npm

Valide a saída. Você deve ver duas versões, por exemplo:

v20.x.x
10.x.x
Enter fullscreen mode Exit fullscreen mode

Se o agente disser que o Node está instalado, mas não mostrar a saída bruta, peça:

Cole a saída completa dos comandos node -v e npm -v.

Se o Node.js não estiver instalado, instale manualmente em nodejs.org e depois continue. Não delegue essa instalação ao agente sem revisar o impacto no seu ambiente.

Passo 2: peça ao agente para instalar o Apidog CLI

Depois de confirmar Node.js e npm, peça ao agente:

Leia https://apidog.com/apidog-cli-installation-guide.md?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation e siga as instruções.

O comando principal será:

npm install -g apidog-cli@latest
Enter fullscreen mode Exit fullscreen mode

A flag -g instala o binário globalmente, deixando o comando apidog disponível no PATH. A tag @latest instala a versão mais recente publicada.

Instalando o Apidog CLI

Depois da instalação, o agente deve verificar:

apidog --version
apidog --help
Enter fullscreen mode Exit fullscreen mode

Verificando o Apidog CLI

Valide duas coisas:

  • apidog --version deve imprimir uma versão real.
  • apidog --help deve listar comandos, incluindo apidog run.

Para uma checagem mais completa, peça ao agente:

Execute este comando e cole a saída completa:

node -v && apidog --version && which node && which apidog
Enter fullscreen mode Exit fullscreen mode

Você deve receber versões e caminhos, por exemplo:

v20.x.x
x.x.x
/usr/local/bin/node
/usr/local/bin/apidog
Enter fullscreen mode Exit fullscreen mode

Se apidog não for encontrado, o problema mais comum é o diretório global de binários do npm não estar no PATH.

Alternativa sem instalação global

Se você não quiser modificar pacotes globais, use npx:

npx apidog-cli --version
Enter fullscreen mode Exit fullscreen mode

Isso é útil em máquinas compartilhadas ou runners efêmeros de CI. Para uso diário local, a instalação global costuma ser mais simples.

Passo 3: autentique sem expor o token ao agente

O CLI precisa de um token de acesso para executar cenários da sua conta. Essa etapa deve ser parcialmente manual, porque o token é um segredo.

Gere o token você mesmo:

  1. Abra o Apidog.
  2. Clique no seu avatar.
  3. Vá em Configurações da Conta.
  4. Acesse Token de Acesso à API.
  5. Gere um novo token.
  6. Copie e armazene em local seguro.

Não cole o token no chat do agente.

Use este prompt:

Eu autenticarei o Apidog CLI por conta própria para que o token fique fora deste chat. Diga-me o comando exato apidog login para executar, então depois que eu confirmar que o executei, execute apidog whoami para verificar se o CLI está autenticado e me mostre o resultado.

No seu próprio terminal, execute:

apidog login --with-token SEU_TOKEN_DE_ACESSO
Enter fullscreen mode Exit fullscreen mode

Depois, peça ao agente para verificar:

apidog whoami
Enter fullscreen mode Exit fullscreen mode

A saída deve identificar sua conta. Se isso acontecer, o CLI está autenticado.

A regra é simples: o agente pode executar testes depois do login, mas não precisa ver o token bruto.

Passo 4: execute um primeiro cenário de teste

O comando principal é:

apidog run
Enter fullscreen mode Exit fullscreen mode

Ele precisa apontar para um cenário de teste pelo ID.

A forma mais segura de obter o comando correto é gerar pelo próprio Apidog:

  1. Abra o cenário de teste no Apidog.
  2. Vá até a aba CI/CD.
  3. Escolha a opção de linha de comando.
  4. Copie o comando gerado.

Ele terá uma estrutura parecida com esta:

apidog run --access-token SEU_TOKEN_DE_ACESSO -t 605067 -e 1629989 -n 1 -r cli
Enter fullscreen mode Exit fullscreen mode

Onde:

  • --access-token autentica a execução.
  • -t define o ID do cenário de teste.
  • -e define o ID do ambiente.
  • -n 1 executa o cenário uma vez.
  • -r cli mostra um relatório legível no terminal.

Como você já fez login localmente, remova o token antes de passar o comando ao agente:

apidog run -t 605067 -e 1629989 -n 1 -r cli
Enter fullscreen mode Exit fullscreen mode

Use este prompt:

Execute meu cenário de teste Apidog com o CLI. Já estou autenticado, então não passe um token de acesso. Use: apidog run -t 605067 -e 1629989 -n 1 -r cli. Mostre-me a saída completa e diga-me o código de saída.

O ponto mais importante é o código de saída:

  • 0: todas as asserções passaram.
  • diferente de 0: houve falha.

Peça sempre o código de saída. É ele que permite usar o comando como gate em CI ou dentro do loop do agente.

Se precisar ver todas as opções disponíveis:

apidog run --help
Enter fullscreen mode Exit fullscreen mode

Para detalhes de flags, reportadores e exemplos de CI, consulte o guia completo do Apidog CLI.

Como usar isso no loop do agente

Depois da instalação e autenticação, executar testes de API vira um comando shell. Isso permite incluir o Apidog no fluxo normal de desenvolvimento assistido por IA.

Exemplo de loop:

  1. O agente altera um handler de API.
  2. Ele executa testes de unidade.
  3. Ele executa o cenário Apidog: 
apidog run -t 605067 -e 1629989 -n 1 -r cli
Enter fullscreen mode Exit fullscreen mode
  1. Se o código de saída for 0, ele continua.
  2. Se falhar, ele lê a asserção quebrada, ajusta o código e roda novamente.

Esse padrão aproxima testes de API do mesmo ciclo que agentes já usam para testes unitários: editar, executar, ler falha, corrigir.

Para uma visão mais ampla desse uso, veja como usar agentes de IA para testes de API.

Como levar o comando para CI

Depois de validar localmente, você pode usar o mesmo comando no pipeline.

O princípio é o mesmo:

apidog run -t 605067 -e 1629989 -n 1 -r cli
Enter fullscreen mode Exit fullscreen mode

Em CI, não faça login manual. Use o token como segredo do pipeline e injete-o na execução, sem expor em logs.

A mecânica de segredos, reportadores e gating por código de saída está no guia Apidog CLI no GitHub Actions.

Integrações mais profundas com agentes

Se você quiser ir além de executar comandos shell, há duas opções relacionadas:

Ambas partem do mesmo apidog-cli configurado neste guia.

Recapitulando

O fluxo completo é:

  1. Verificar Node.js e npm: 
node -v
npm -v
Enter fullscreen mode Exit fullscreen mode
  1. Instalar o CLI: 
npm install -g apidog-cli@latest
Enter fullscreen mode Exit fullscreen mode
  1. Confirmar a instalação: 
apidog --version
apidog --help
Enter fullscreen mode Exit fullscreen mode
  1. Autenticar manualmente sem expor o token ao agente: 
apidog login --with-token SEU_TOKEN_DE_ACESSO
Enter fullscreen mode Exit fullscreen mode
  1. Verificar a conta: 
apidog whoami
Enter fullscreen mode Exit fullscreen mode
  1. Executar um cenário: 
apidog run -t 605067 -e 1629989 -n 1 -r cli
Enter fullscreen mode Exit fullscreen mode

A partir daí, seu agente pode executar testes de API como parte do próprio ciclo de trabalho. Você continua criando cenários visualmente no Apidog, enquanto o agente e o CI os executam automaticamente.

Próximos passos:

Top comments (0)