DEV Community

Cover image for Como Usar a CLI do Apidog no Hermes Agent
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Usar a CLI do Apidog no Hermes Agent

O Hermes Agent roda no seu terminal, mantém contexto entre sessões e executa comandos de shell reais. Isso permite usar o Hermes como parte do seu loop de testes de API: se ele consegue executar um comando, ele consegue executar seus cenários do Apidog.

Experimente o Apidog hoje

O executor é a CLI do Apidog, o pacote npm apidog-cli. Ela executa, direto do terminal, os cenários de teste criados visualmente no Apidog e retorna um código de saída que o Hermes pode interpretar.

Neste guia, você vai configurar o Hermes para:

  1. Ler instruções de teste a partir de AGENTS.md.
  2. Executar apidog run usando a ferramenta terminal.
  3. Validar o resultado pelo código de saída.
  4. Opcionalmente, conectar o servidor Apidog MCP para que o Hermes também leia a especificação da API enquanto codifica.

Se a CLI ainda não estiver instalada, siga primeiro o guia como instalar a CLI do Apidog com um agente de codificação de IA. Volte quando este comando imprimir uma versão:

apidog --version
Enter fullscreen mode Exit fullscreen mode

Você também precisa de uma conta Apidog com pelo menos um cenário de teste salvo.

O que significa usar a CLI do Apidog no Hermes

O Hermes Agent, construído pela Nous Research, roda no terminal e executa ações por meio de ferramentas integradas. Para este fluxo, a ferramenta importante é terminal.

Na prática, usar a CLI do Apidog no Hermes significa:

  1. Registrar o fluxo de trabalho em um arquivo de contexto, como AGENTS.md, para que o Hermes saiba qual comando executar.
  2. Executar apidog run pela ferramenta terminal, como qualquer outro comando de shell.
  3. Tratar o código de saída como fonte da verdade:
    • 0: todas as asserções passaram.
    • diferente de 0: houve falha.
  4. Opcionalmente, conectar o servidor Apidog MCP, para expor a especificação da API ao Hermes durante a implementação.

Não é necessário instalar um plugin específico do Apidog no Hermes. O Hermes só precisa saber qual comando executar e como interpretar o resultado.

O mecanismo: arquivo de contexto em vez de lembrete no chat

O Hermes carrega contexto do projeto no início da sessão. Ele procura arquivos de instrução no diretório de trabalho, incluindo:

  • AGENTS.md
  • CLAUDE.md

Esses arquivos são injetados no prompt do sistema. Portanto, se o seu repositório já usa AGENTS.md, o Hermes também consegue ler essas instruções.

Colocar o comando no chat funciona apenas para a sessão atual. Colocar o comando em AGENTS.md torna o fluxo reutilizável por:

  • você;
  • outros membros do time;
  • futuras sessões do Hermes;
  • automações locais baseadas no mesmo repositório.

O Hermes também lê SOUL.md, mas esse arquivo é voltado à persona do agente. Mantenha instruções de teste no AGENTS.md.

Passo 1: adicione um bloco Apidog ao AGENTS.md

Na raiz do repositório, abra ou crie o arquivo AGENTS.md:

touch AGENTS.md
Enter fullscreen mode Exit fullscreen mode

Adicione um bloco com o comando real que o Hermes deve executar:

## API testing with the Apidog CLI

This repo uses the Apidog CLI (`apidog-cli`, the `apidog` command) to run API
test scenarios. The scenarios live in our Apidog project, not in this repo.

When you change an API handler, route, or response shape, run the relevant
Apidog scenario through the terminal tool before considering the change done:

    apidog run -t 605067 -e 1629989 -n 1 -r cli

- `-t 605067` is the checkout-flow test scenario.
- `-e 1629989` is the staging environment.
- The machine is already authenticated via `apidog login`, so do NOT pass
  an access token and do NOT print one.

Treat the exit code as the source of truth: `0` means every assertion passed,
non-zero means a failure. If it exits non-zero, read the failing assertion in
the report and fix the code, then re-run. Do not report a pass on a non-zero
exit.
Enter fullscreen mode Exit fullscreen mode

Substitua:

  • 605067 pelo ID real do cenário;
  • 1629989 pelo ID real do ambiente.

Use normalmente um ambiente de staging ou desenvolvimento local. Evite apontar o Hermes para produção.

Esse bloco é importante por dois motivos:

  1. Ele fornece o comando exato, evitando que o Hermes invente flags.
  2. Ele define que o código de saída tem prioridade sobre qualquer resumo textual.

Isso reduz a chance de o agente declarar “testes passaram” quando a execução falhou.

Passo 2: copie o comando gerado pelo Apidog

Antes de pedir ao Hermes para executar o teste, obtenha um comando válido no Apidog.

No Apidog:

  1. Abra o cenário de teste.
  2. Vá para a aba CI/CD.
  3. Escolha a opção de linha de comando.
  4. Copie o comando apidog run.

O comando gerado terá este formato:

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

Onde:

  • 605067 é o ID do cenário;
  • 1629989 é o ID do ambiente;
  • YOUR_ACCESS_TOKEN é o token de acesso.

Como a máquina já deve estar autenticada via apidog login, remova --access-token YOUR_ACCESS_TOKEN antes de colocar o comando no AGENTS.md.

Use este formato no contexto do Hermes:

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

Passo 3: peça ao Hermes para executar o teste

Inicie o Hermes na raiz do repositório e peça para executar o cenário de acordo com o AGENTS.md.

Exemplo de prompt:

Execute nosso cenário de teste de API do Apidog da maneira que AGENTS.md descreve. 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 Hermes deve chamar a ferramenta terminal e executar:

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

O reporter -r cli mostra a execução passo a passo no terminal, incluindo requisições, respostas e asserções.

Dependendo da configuração do Hermes, você pode ver um prompt de aprovação antes da execução. Para um cenário somente leitura contra staging, esse é um comando normalmente seguro para permitir.

Passo 4: valide pelo código de saída

Não valide apenas pelo texto do resumo. Valide pelo código de saída.

A regra é:

exit code 0     => todas as asserções passaram
exit code != 0  => houve falha
Enter fullscreen mode Exit fullscreen mode

Se o Hermes disser que os testes passaram, mas o código de saída for diferente de 0, considere a execução falha.

Esse comportamento torna o apidog run útil tanto para o loop local do Hermes quanto para CI/CD.

Para consultar flags disponíveis, peça ao Hermes para executar:

apidog run --help
Enter fullscreen mode Exit fullscreen mode

O guia completo da CLI do Apidog documenta os principais flags, incluindo reporters como:

  • cli
  • html
  • json
  • junit

Passo 5: integre o teste ao loop de edição do Hermes

O objetivo é fazer o Hermes executar o teste sem você precisar repetir o comando toda vez.

Um fluxo prático fica assim:

  1. O Hermes altera um handler, rota ou formato de resposta.
  2. Ele identifica, via AGENTS.md, que deve executar o cenário do Apidog.
  3. Ele roda: 
apidog run -t 605067 -e 1629989 -n 1 -r cli
Enter fullscreen mode Exit fullscreen mode
  1. Ele lê o código de saída.
  2. Se for 0, continua.
  3. Se for diferente de 0, lê a asserção com falha, corrige o código e executa novamente.

Isso transforma o cenário de API em parte do mesmo ciclo de desenvolvimento que testes unitários:

editar código -> executar teste -> ler falha -> corrigir -> executar novamente
Enter fullscreen mode Exit fullscreen mode

Esse é o modelo de “delegar e verificar”: o Hermes executa o comando, mas você mantém a regra objetiva de validação pelo código de saída.

Para execuções longas, pastas grandes ou múltiplas iterações, a ferramenta terminal do Hermes aceita background=true. Assim, o Hermes pode iniciar a execução em segundo plano, continuar trabalhando e consultar o resultado depois.

Para padrões mais amplos, veja também:

Opcional: conecte o servidor Apidog MCP

A CLI permite ao Hermes executar testes. O servidor Apidog MCP permite que ele leia a especificação da API enquanto escreve código.

Os dois recursos se complementam:

  • MCP fornece o contrato da API ao Hermes.
  • CLI valida a implementação contra cenários reais.

O Hermes suporta o Model Context Protocol, ou MCP, nativamente.

Edite o arquivo:

~/.hermes/config.yaml
Enter fullscreen mode Exit fullscreen mode

Adicione uma entrada em mcp_servers:

mcp_servers:
  apidog:
    command: "npx"
    args: ["-y", "apidog-mcp-server@latest", "--project=YOUR_PROJECT_ID"]
    env:
      APIDOG_ACCESS_TOKEN: "YOUR_ACCESS_TOKEN"
Enter fullscreen mode Exit fullscreen mode

Depois de salvar, dentro do Hermes, execute:

/reload-mcp
Enter fullscreen mode Exit fullscreen mode

Ou reinicie o Hermes.

Na inicialização, o Hermes descobre os servidores MCP e registra suas ferramentas com namespace, como:

mcp_apidog_<tool>
Enter fullscreen mode Exit fullscreen mode

Assim, o agente pode consultar a especificação da API durante o raciocínio normal.

Para a configuração completa, incluindo ID do projeto e token, consulte o guia do servidor Apidog MCP.

Para uma versão empacotada desse loop, veja o guia da CLI do Apidog com Habilidades Claude.

Do loop local para a CI

Depois que o Hermes executa o cenário localmente e valida pelo código de saída, você tem o mesmo comando que pode ser usado na pipeline.

A diferença é a autenticação:

  • localmente: login já armazenado via apidog login;
  • na CI: token passado como segredo mascarado.

Você pode pedir ao Hermes para criar o passo de CI:

Escreva um passo do GitHub Actions que instale o apidog-cli e execute apidog run -t 605067 -e 1629989 -r junit, lendo o token de acesso de um segredo do repositório chamado APIDOG_ACCESS_TOKEN.

Um exemplo de estrutura seria:

- name: Install Apidog CLI
  run: npm install -g apidog-cli

- name: Run Apidog API tests
  run: apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit
  env:
    APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

Os detalhes de segredos, reporters e validação por código de saída estão em CLI do Apidog no GitHub Actions.

Com isso, o mesmo comando passa a existir em três lugares:

  1. no seu terminal;
  2. no loop do Hermes;
  3. na CI.

Todos usando o mesmo critério objetivo: o código de saída.

Armadilhas comuns

O Hermes ignora o bloco de contexto

Verifique se o arquivo está com o nome correto:

AGENTS.md
Enter fullscreen mode Exit fullscreen mode

ou:

CLAUDE.md
Enter fullscreen mode Exit fullscreen mode

Também confirme que ele está no diretório onde o Hermes foi iniciado.

Se necessário, reinicie a sessão para forçar uma nova leitura do contexto.

O Hermes apenas sugere o comando, mas não executa

O Hermes executa comandos pela ferramenta terminal, geralmente atrás de uma camada de aprovação.

Se houver uma execução pendente, aprove-a. Se a configuração estiver bloqueando comandos de terminal, permita pelo menos:

apidog run
Enter fullscreen mode Exit fullscreen mode

apidog whoami mostra que você não está autenticado

O login é armazenado na máquina, não no Hermes.

Faça login manualmente:

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

Depois peça ao Hermes para confirmar:

apidog whoami
Enter fullscreen mode Exit fullscreen mode

Não cole tokens no chat se isso puder expô-los em logs ou histórico.

O Hermes inventa um flag

Se você vir erro de opção desconhecida, o Hermes provavelmente inferiu um flag inexistente.

Peça para ele consultar a ajuda:

apidog run --help
Enter fullscreen mode Exit fullscreen mode

Depois atualize o AGENTS.md com o flag correto.

O Hermes relata sucesso em uma execução com falha

Essa é a falha mais importante a evitar.

Sempre peça o código de saída e compare:

0    => sucesso
!= 0 => falha
Enter fullscreen mode Exit fullscreen mode

Quando o resumo textual e o código de saída discordarem, confie no código de saída.

Conclusão

A configuração prática é simples:

  1. Adicione um bloco no AGENTS.md com o comando apidog run.
  2. Remova tokens do arquivo de contexto.
  3. Instrua o Hermes a executar o comando pela ferramenta terminal.
  4. Valide sempre pelo código de saída.
  5. Opcionalmente, conecte o servidor Apidog MCP em ~/.hermes/config.yaml.

Você continua criando cenários visualmente no Apidog. O Hermes apenas executa esses cenários e usa o resultado para orientar o loop de implementação.

A partir daqui, você pode levar o mesmo comando para sua pipeline com a CLI do Apidog no GitHub Actions ou consultar todos os flags no guia completo.

Perguntas frequentes

Preciso de um plugin Hermes para usar a CLI do Apidog?

Não. O Hermes executa comandos de shell pela ferramenta terminal, então ele pode chamar apidog run diretamente.

A configuração específica do Hermes é o bloco em AGENTS.md. O servidor MCP é opcional.

Onde coloco as instruções que ensinam o fluxo de trabalho ao Hermes?

Coloque em um arquivo de contexto que o Hermes carrega na inicialização, como:

AGENTS.md
Enter fullscreen mode Exit fullscreen mode

ou:

CLAUDE.md
Enter fullscreen mode Exit fullscreen mode

O local recomendado é a raiz do repositório.

Como garanto que o Hermes não simule um teste aprovado?

Peça sempre o código de saída.

apidog run retorna 0 somente quando todas as asserções passam. Se o texto do Hermes disser “passou”, mas o código de saída for diferente de 0, considere falha.

Como conecto o servidor Apidog MCP ao Hermes?

Adicione uma entrada mcp_servers em:

~/.hermes/config.yaml
Enter fullscreen mode Exit fullscreen mode

Use o comando apidog-mcp-server com o ID do projeto e o token. Depois execute:

/reload-mcp
Enter fullscreen mode Exit fullscreen mode

Ou reinicie o Hermes.

O guia do servidor Apidog MCP cobre os detalhes de projeto e autenticação.

Isso funciona da mesma forma em outros agentes de codificação de IA?

A CLI é a mesma. O que muda é como você instrui o agente.

No Hermes, use AGENTS.md e a ferramenta terminal. Outros agentes podem usar outros arquivos de instrução ou mecanismos de contexto.

A instalação e autenticação continuam iguais, então o guia de instalação também se aplica.

Top comments (0)