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

Você já tem um agente de codificação de IA aberto. Ele edita seus arquivos, executa seus testes e lê a saída do seu terminal. Então, por que você está prestes a instalar uma ferramenta de linha de comando manualmente, copiando comandos npm de uma aba e colando-os um por um?

Você não precisa. O Apidog CLI é um pacote npm chamado apidog-cli que executa os cenários de teste de API que você construiu no Apidog, diretamente de um terminal. Instalar o Apidog CLI é uma curta sequência de comandos shell, uma etapa de autenticação e uma primeira execução. Esse é exatamente o tipo de trabalho mecânico que um agente como Claude Code, Cursor, Windsurf ou GitHub Copilot no modo agente faz bem. Você descreve o objetivo, o agente executa os comandos reais e você verifica o trabalho dele.

Este guia mostra esse fluxo de trabalho de ponta a ponta. Você verá os prompts exatos para dar ao seu agente, os comandos que ele executará e como verificar cada etapa em vez de apenas confiar na palavra do agente. A recompensa no final é a parte que vale a pena a configuração: uma vez que o CLI estiver instalado e autenticado, seu agente poderá executar seus testes do Apidog por conta própria, dentro de seu próprio loop ou em CI, e ler o resultado de aprovação ou falha. Para acompanhar, você precisa de uma conta Apidog com pelo menos um projeto. Baixe o Apidog primeiro se ainda não tiver uma.

Por que deixar um agente fazer a instalação

Nada sobre os comandos de instalação muda quando um agente os executa. É o mesmo npm install -g apidog-cli@latest que você digitaria. O que muda é quem digita e quem lê a saída.

Um agente é bom nisso por três razões concretas. Ele pode executar um comando, ler o status de saída e o texto impresso, e decidir o próximo passo a partir do que realmente viu, de modo que um “comando não encontrado” não trave da mesma forma que travaria em um loop de copiar e colar. Ele já tem seu shell, sua versão do Node e seu PATH à sua frente, então ele adapta a correção à sua máquina em vez de uma genérica. E ele faz as partes chatas, verificando o Node primeiro, verificando a versão após a instalação, confirmando a autenticação, sem que você precise supervisionar cada linha.

O que você precisa antes de começar

O CLI é distribuído como um pacote npm, então a única dependência de sistema é um ambiente de execução Node.js. Três coisas precisam ser verdadeiras:

1. Node.js e npm estão instalados. O pacote é instalado via npm e executa no Node. Uma versão LTS atual é a escolha segura em qualquer máquina de desenvolvedor.
2. Uma conta Apidog com acesso a projetos. O CLI não armazena seus próprios testes. Ele acessa seu projeto Apidog e executa os cenários que estão lá, então você precisa de uma conta que possa ver pelo menos um projeto.
3. Um cenário de teste para executar. O executor executa cenários, não requisições soltas. Crie um no aplicativo Apidog primeiro: encadeie algumas requisições, adicione asserções e salve-o. Se você é novo em escrever verificações contra respostas, Asserções de API: um guia prático explica como fazer.

Você também precisa de um agente de codificação de IA com permissão para executar comandos shell. Claude Code, o agente do Cursor, Cascade do Windsurf e o modo agente do GitHub Copilot se qualificam. A única coisa a confirmar antes de começar é que seu agente tem permissão para executar comandos no seu terminal, não apenas sugeri-los. Se ele só pode imprimir comandos para você colar, você ainda pode seguir este guia, você será apenas quem pressionará Enter.

Passo 1: Peça ao agente para verificar o ambiente

Comece permitindo que o agente confirme se o Node está presente, para que ele saiba se pode ou não instalar. Um prompt como este funciona:

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 executará:

node -v
npm -v

Ele deve relatar dois números de versão para você. Sua verificação: leia as versões que ele imprime. Se ele alegar que o Node está instalado, mas não mostrar uma string de versão, peça para ele colar a saída bruta do comando. A razão para a frase “não instale o Node você mesmo” no prompt é que instalar um ambiente de execução é uma decisão maior e específica da máquina que você quer tomar deliberadamente, não algo para delegar cegamente. Se o Node estiver faltando, instale-o em nodejs.org você mesmo, e então continue.

Passo 2: Peça ao agente para instalar o CLI

Assim que o Node for confirmado, delegue a instalação:

Leia https://apidog.com/apidog-cli-installation-guide.md e siga as instruções.

O agente executará o comando de instalação.

A flag -g coloca o binário apidog no seu PATH global em vez de nos node_modules de um projeto. A tag @latest puxa a versão mais recente publicada, que é o que você deseja para uma primeira instalação. Quando o npm termina, o binário é nomeado apidog, então todo comando a partir daqui começa com apidog.

Então ele verificará:

apidog --version
apidog --help

Sua verificação: esta é a verificação mais importante em todo o processo, porque é o lugar mais fácil para um agente alegar sucesso que não obteve. Certifique-se de que apidog --version imprimiu um número de versão real, não um “comando não encontrado” que o agente ignorou. A saída --help deve listar apidog run e suas opções. Se você quiser uma única linha que você mesmo possa executar para confirmar que tanto o binário quanto o ambiente de execução por trás dele se resolvem, peça ao agente para executar isso e colar o resultado:

node -v && apidog --version && which node && which apidog

Se cada linha retornar uma versão ou um caminho, a instalação está limpa. Se o agente relatar problemas, a causa mais comum é o diretório global de binários não estar no seu PATH; a seção de solução de problemas no final aborda isso.

Se você preferir que o agente não modifique seus pacotes globais, diga a ele para usar npx em vez disso. npx apidog-cli --version busca o pacote, o executa e não deixa nada para trás no seu PATH, o que é adequado para uma máquina compartilhada ou um executor de CI efêmero. Para uma máquina que você usa todos os dias, a instalação global é mais simples e rápida em chamadas repetidas.

Passo 3: Peça ao agente para autenticar, mas você lida com o token

O CLI executa cenários da sua conta, então ele precisa provar que tem permissão. Ele faz isso com um token de acesso. Esta é a única etapa que você não delega totalmente, porque o token é um segredo e você não quer que ele seja colado em uma transcrição de chat, um arquivo de log, ou em qualquer lugar onde o agente possa ecoá-lo de volta.

Gere o token você mesmo primeiro. Abra o aplicativo Apidog ou o console web, clique no seu avatar de usuário, vá para Configurações da Conta, depois Token de Acesso à API, e gere um novo. Copie-o para um local seguro e trate-o como uma senha, porque qualquer pessoa que o possuir poderá executar cenários como você.

Então, solicite ao agente sem nunca colocar o token no 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.

Você executa o comando de login no seu próprio terminal:

apidog login --with-token SEU_TOKEN_DE_ACESSO

Deixe o agente executar a verificação:

apidog whoami

Sua verificação: apidog whoami deve imprimir sua conta. Se isso acontecer, a autenticação está configurada. A razão para manter o token em suas mãos é uma simples higiene operacional: um token que cai na janela de contexto de um agente pode acabar em logs ou em uma transcrição salva. O comando de login o armazena localmente em sua máquina, então o agente nunca precisa ver a string bruta para executar testes depois. Para CI, a regra é a mesma, mas mais rigorosa, o que a última seção aborda.

Passo 4: Peça ao agente para fazer uma primeira execução de teste

Agora, vá de “instalado” para “realmente executou”. O comando principal é apidog run, apontado para um cenário pelo seu ID.

A maneira mais limpa de obter um comando correto é deixar o Apidog construí-lo para você. Abra o cenário de teste no Apidog, mude para a aba CI/CD, escolha a opção de linha de comando, e o Apidog gerará o comando completo apidog run com o ID do cenário, ID do ambiente e um token de acesso já preenchidos. Copie isso, e você terá um ponto de partida válido garantido. Fica assim:

apidog run --access-token SEU_TOKEN_DE_ACESSO -t 605067 -e 1629989 -n 1 -r cli

Aqui está o que cada parte faz. --access-token autentica a execução. -t nomeia o cenário de teste pelo ID (605067 é um placeholder; o seu será diferente). -e seleciona o ambiente para executar, como desenvolvimento ou staging. -n 1 executa o cenário uma vez. -r cli escreve um relatório legível no seu terminal.

Como você já fez login, você pode entregar ao agente os IDs sem o token e deixá-lo executar:

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 agente executará o cenário e relatará a execução passo a passo e um resumo. Sua verificação: peça o código de saída explicitamente, porque esse é o sinal do qual tudo a jusante depende. apidog run sai com 0 quando todas as asserções passam e com um código diferente de zero quando algo falha. Esse comportamento único é o que permite que um pipeline, ou um agente, trate a execução como um portão de aprovação ou falha limpo sem fiação extra. Se o agente disser “testes aprovados”, mas o código de saída for diferente de zero, ele está errado; confie no código, não na prosa.

Quer um formato de relatório diferente ou mais iterações? Peça ao agente para executar apidog run --help, que imprime todas as flags que o executor suporta, incluindo os outros reportadores e as opções de iteração orientada por dados. Para a referência completa das flags e exemplos de CI, o guia completo do Apidog CLI aborda cada uma.

A recompensa: agora o agente pode testar por conta própria

É por isso que a configuração valeu a pena. Com o CLI instalado e autenticado, executar um teste Apidog agora é um único comando shell que seu agente pode emitir a qualquer momento e ler o resultado. Isso integra os testes de API ao loop normal do agente.

Imagine o agente mudando um manipulador que afeta um endpoint. Em vez de editar o código e declarar vitória, ele pode executar seu cenário Apidog contra o ambiente afetado, ler o código de saída e agir: verde, ele avança; vermelho, ele lê a asserção falha no relatório e tenta uma correção. O teste se torna parte do loop de feedback do agente, da mesma forma que ele já executa seus testes de unidade. Para uma visão mais ampla desse padrão, como usar agentes de IA para testes de API aborda onde ele se encaixa e onde não se encaixa.

Isso se estende diretamente para o CI, onde o agente nem sequer está presente. Depois de ver o comando funcionar localmente, você pode pedir ao agente para escrever a etapa do pipeline que o executa a cada push. A mecânica disso, segredos, reportadores, gating por código de saída, está em Apidog CLI no GitHub Actions.

Se você deseja que a integração do agente vá mais fundo do que a execução de comandos shell, duas funcionalidades do Apidog conectam os agentes às suas especificações e cenários de API de forma mais direta. O servidor Apidog MCP expõe suas especificações de API a ferramentas de codificação de IA através do Protocolo de Contexto do Modelo, para que o agente possa ler seu esquema enquanto codifica. E o Apidog CLI com Claude Skills empacota o fluxo de trabalho do CLI em uma habilidade reutilizável, para que a etapa de execução de testes se torne algo que o Claude busca por conta própria. Ambos são construídos sobre o mesmo apidog-cli instalado que você acabou de configurar.

Da instalação delegada a um loop testado

Esse é todo o caminho. Você confirma o Node, o agente instala apidog-cli com um comando npm, você verifica com apidog --version, você autentica com um token que você mantém em suas próprias mãos, e o agente executa um primeiro apidog run enquanto você verifica o código de saída. Alguns minutos de delegar e depois verificar, e seu agente agora pode executar seus testes de API por conta própria.

A razão pela qual isso importa é a mesma razão pela qual qualquer portão de teste importa, com um adendo. Testes presos atrás de uma GUI só são executados quando um humano clica. Um comando de uma linha é executado a cada push. E uma vez que esse comando está ao alcance do seu agente de codificação, ele é executado dentro do próprio loop de editar-testar-corrigir do agente, em mudanças que você ainda nem revisou. Você continua criando cenários visualmente no Apidog, e tanto seu pipeline quanto seu agente os executam onde nenhum humano está observando.

A partir daqui, aponte o mesmo comando para o CI em Apidog CLI no GitHub Actions, ou leia a referência completa das flags no guia completo do Apidog CLI.