Hermes Agent에서 Apidog CLI 사용법

Hermes Agent는 터미널에서 실행되며, 세션 간 학습 내용을 기억하고, 실제 셸 명령을 사용하여 작업을 수행합니다. 이 마지막 부분이 핵심입니다: 명령을 실행할 수 있다면, API 테스트도 실행할 수 있습니다.

이들을 연결하는 실행기는 `apidog-cli`라는 npm 패키지인 Apidog CLI입니다. Apidog CLI는 Apidog에서 시각적으로 구축한 테스트 시나리오를 터미널에서 직접 실행하고, Hermes가 처리할 수 있는 상태 코드를 반환하며 종료됩니다. 이 가이드는 Hermes 관련 절반을 다룹니다: 명령을 실행하는 `terminal` 도구, Hermes에게 워크플로우를 가르치는 컨텍스트 파일, 실행이 Hermes의 루프에 통합되는 방식, 그리고 Hermes가 작업하는 동안 API 사양을 제공하는 선택적 Apidog MCP 서버입니다.

CLI가 아직 설치되지 않았다면, AI 코딩 에이전트를 사용하여 Apidog CLI를 설치하는 방법부터 시작하세요. 이 가이드는 에이전트에게 설치 및 인증 과정을 안내합니다. `apidog --version` 명령이 숫자를 출력하면 다시 돌아오세요. 또한, 최소 하나 이상의 저장된 테스트 시나리오가 있는 Apidog 계정이 필요합니다. 계정이 없다면 Apidog을 다운로드하세요.

버튼

Hermes에서 "CLI 사용"이 의미하는 것

Nous Research가 개발한 Hermes Agent는 터미널에서 실행되며, AI 모델과 대화하고, 내장 도구를 통해 동작합니다. 여기서 중요한 도구는 `terminal` 도구입니다. Hermes는 작업 디렉터리에서 `terminal` 도구를 호출하여 셸 명령을 실행하고, 그 출력을 다시 자신의 추론에 사용합니다. 설치할 Apidog 플러그인은 없으며, 필요하지도 않습니다. Hermes에서 Apidog CLI를 사용하는 것은 세 가지를 의미합니다:

워크플로우를 Hermes에게 한 번 가르칩니다: Hermes가 시작 시 로드하는 컨텍스트 파일에 워크플로우를 작성하여, Hermes가 명령, 플래그, 그리고 종료 코드가 진실의 근원임을 알도록 합니다.
Hermes가 `terminal` 도구를 통해 `apidog run`을 실행하도록 합니다: 다른 명령과 마찬가지로 실행합니다.
선택적으로 Apidog MCP 서버를 연결합니다: Hermes가 테스트가 확인하는 코드를 작성하는 동안 API 사양을 읽을 수 있도록 합니다.

컨텍스트 파일은 이 가이드를 일반적인 "터미널을 열고 입력"하는 방식 대신 Hermes에 맞춰 만들고, 일회성 "내 테스트 실행"을 Hermes가 스스로 수행하는 작업으로 전환시킵니다.

메커니즘: 채팅 알림이 아닌 컨텍스트 파일

Hermes는 세션 시작 시 프로젝트 컨텍스트를 로드합니다. 컨텍스트 엔진은 작업 디렉터리에서 `CLAUDE.md` 및 `AGENTS.md`와 같은 지시 파일을 스캔하여 시스템 프롬프트에 주입합니다. 이는 Claude Code와 Codex가 사용하는 것과 동일한 규칙이므로, 저장소에 이미 `AGENTS.md` 파일이 있다면 Hermes도 이를 읽습니다.

이것이 바로 CLI를 채팅에서 언급하는 대신 컨텍스트 파일에 작성하는 이유입니다. 세션에 입력된 시나리오 ID는 세션이 끝나면 사라지지만, `AGENTS.md`에 있는 시나리오 ID는 앞으로 모든 팀원과 모든 Hermes 실행에서 사용할 수 있습니다. (Hermes는 `SOUL.md`도 읽지만, 이것은 프로젝트가 아닌 에이전트의 페르소나를 위한 것입니다. 테스트 지침은 `AGENTS.md`에 보관하세요.)

1단계: 컨텍스트 파일에 Apidog 블록 추가

저장소 루트에서 `AGENTS.md` 파일을 열거나 새로 생성하고, Hermes에게 CLI의 존재, 실행 방법, 결과 해석 방법을 알려주는 섹션을 추가하세요. 설명 대신 실제 명령과 ID를 제공해야 합니다.

## 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`는 결제 흐름 테스트 시나리오입니다.
- `-e 1629989`는 스테이징 환경입니다.
- 이 컴퓨터는 이미 `apidog login`을 통해 인증되었으므로, 액세스 토큰을 전달하거나 출력하지 마십시오.

종료 코드를 진실의 근원으로 간주하십시오: `0`은 모든 단언이 통과했음을 의미하고, 0이 아닌 값은 실패를 의미합니다. 0이 아닌 값으로 종료되면 보고서에서 실패한 단언을 읽고 코드를 수정한 다음 다시 실행하십시오. 0이 아닌 종료 시 통과로 보고하지 마십시오.

`605067`을 실제 시나리오 ID로, `1629989`를 Hermes가 정상 작업 중에 사용해야 하는 환경(일반적으로 스테이징 또는 로컬 개발 환경이며, 프로덕션은 절대 아님)으로 바꾸세요. 올바른 ID를 얻으려면, Apidog 시나리오의 CI/CD 탭에서 Apidog이 생성하는 `apidog run` 명령을 복사한 다음(다음 섹션에서 다룸), 붙여넣기 전에 액세스 토큰을 삭제하세요. 컴퓨터가 이미 로그인되어 있고 토큰은 커밋된 파일에 속하지 않기 때문입니다.

이 블록이 작동하는 데에는 두 가지가 중요합니다. 첫째, 명령을 정확히 명시하여 Hermes가 플래그를 추측하지 않도록 합니다. 둘째, 합격/불합격 규칙을 명확하게 설명하여 Hermes가 자신의 요약보다 종료 코드를 우선시해야 한다는 것을 알게 합니다. 이는 가장 흔한 에이전트 실패, 즉 실패한 실행 위에 자신감 있게 "테스트 통과"라고 보고하는 것을 방지해 줍니다.

2단계: Apidog에서 명령 가져오기

Hermes에게 실행을 요청하기 전에 제대로 작동하는 명령을 확보하세요. Apidog에서 시나리오를 열고 CI/CD 탭으로 전환한 다음, 명령줄 옵션을 선택하세요. Apidog은 ID와 액세스 토큰이 채워진 전체 `apidog run` 명령을 생성합니다:

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

`605067`은 시나리오 ID이고 `1629989`는 환경 ID입니다. 사용자마다 다를 수 있습니다. 설치 중 CLI를 인증했으므로 `--access-token` 부분을 삭제하고 ID는 유지하세요. 이것이 바로 컨텍스트 파일이 Hermes에게 사용하라고 지시한 명령입니다.

3단계: Hermes가 테스트를 실행하도록 하기

저장소에서 Hermes를 시작한 다음, 검사를 실행하도록 요청하세요. 블록이 설정되면 프롬프트는 다음과 같이 짧아집니다:

우리 Apidog API 테스트 시나리오를 AGENTS.md에 설명된 방식으로 실행해 주세요. 저는 이미 인증되었으니 액세스 토큰을 전달하지 마세요. `apidog run -t 605067 -e 1629989 -n 1 -r cli`를 사용하세요. 전체 출력과 종료 코드를 보여주세요.

Hermes는 `terminal` 도구를 호출하여 작업 디렉터리에서 명령을 실행하고, `-r cli` 리포터는 단계별 결과를 Hermes의 컨텍스트로 다시 스트리밍하여 각 요청과 단언을 확인할 수 있게 합니다. Hermes는 승인 계층을 통해 명령을 라우팅하므로, 설정에 따라 실행 전에 프롬프트가 표시될 수 있습니다. 스테이징 환경에 대한 읽기 전용 테스트 시나리오는 허용해도 되는 안전한 작업 공간 내 명령에 해당합니다.

확인 사항: 요약이 아니라 종료 코드를 확인하십시오. `apidog run`은 모든 단언이 통과할 때 `0`으로 종료하고, 하나라도 실패하면 0이 아닌 값으로 종료합니다. 이러한 동작이 CI와 Hermes 모두에서 이것이 게이트 역할을 하는 전체 이유입니다. Hermes가 "테스트 통과"라고 말했지만 종료 코드가 0이 아니었다면, Hermes가 틀린 것입니다. 코드를 신뢰하십시오. 이것이 1단계 블록이 방지하는 실패입니다.

다른 보고서 형식이나 더 많은 반복을 원한다면, Hermes에게 `apidog run --help`를 실행하여 실제 플래그 목록을 읽도록 하세요. Apidog CLI 전체 가이드는 `html`, `json`, `junit` 리포터를 포함한 모든 플래그를 문서화하고 있습니다.

4단계: Hermes 자체 루프 내에서 테스트하기

핵심은 여러분이 요청하는 것을 멈추고 Hermes가 `AGENTS.md`의 지시에 따라 스스로 시나리오를 실행할 때 발생하는 일입니다. 예를 들어, 결제 응답을 구성하는 핸들러를 편집하는 상황을 상상해 보세요: Hermes는 코드를 편집하고, `terminal` 도구를 통해 스테이징 환경에 대해 Apidog 시나리오를 실행하고, 종료 코드를 읽고, 이에 따라 조치합니다. 녹색(성공)이면 다음으로 진행합니다. 빨간색(실패)이면 보고서를 열고 어떤 단언이 실패했는지(상태 코드, 누락된 필드, 잘못된 값) 읽고, 수정 시도를 한 다음, 다시 실행합니다. API 테스트는 이미 유닛 테스트를 실행하는 것과 동일한 편집-테스트-수정 루프의 일부가 됩니다. 여러분은 단 하나의 지시를 작성했고, Hermes는 이 명령을 기존의 작동 방식에 통합했습니다.

이것은 모든 에이전트 워크플로우를 안전하게 만드는 위임-검증 모델입니다. Hermes는 명령을 실행하고 결과를 읽으며, 여러분은 Apidog에서 시나리오를 계속 작성하고 Hermes가 종료 코드를 정직하게 읽는지 확인합니다. 느린 실행, 큰 폴더 또는 높은 반복 횟수의 경우, `terminal` 도구는 `background=true` 플래그를 받아 Hermes가 스윕을 시작하고 계속 작업하며 블로킹 대신 종료 코드를 폴링할 수 있도록 합니다. 더 넓은 패턴에 대해서는 API 테스트를 위한 AI 에이전트 사용 방법 및 Apidog AI 테스트 하네스를 참조하세요.

선택 사항: Apidog MCP 서버 연결

CLI는 Hermes가 테스트를 실행하게 합니다. Apidog MCP 서버는 코드를 작성하는 동안 API 사양을 읽을 수 있게 합니다. 이 두 가지는 서로 보완적입니다: MCP는 Hermes에게 스키마를 제공하여 계약에 맞는 코드를 생성하도록 하고, CLI는 실제 시나리오에 대해 해당 코드를 검증합니다.

Hermes는 기본적으로 모델 컨텍스트 프로토콜을 지원합니다. `~/.hermes/config.yaml`을 편집하고 `mcp_servers` 섹션 아래에 항목을 추가하세요. Apidog과 같은 로컬 stdio 서버의 경우, 이는 `command`, `args` 배열, 그리고 모든 `env` 값입니다:

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

저장 후 Hermes 내에서 `/reload-mcp`를 실행하거나 Hermes를 다시 시작하세요. Hermes는 시작 시 MCP 서버를 발견하고 `mcp_apidog_<tool>`로 네임스페이스가 지정된 도구를 일반 레지스트리에 등록하므로, 에이전트가 정상적인 추론 중에 이들을 활용합니다. 프로젝트 ID 및 토큰을 포함한 전체 설정은 Apidog MCP 서버 가이드를 참조하세요. 이 루프의 패키지 버전은 Claude Skills 가이드와 함께 Apidog CLI를 참조하세요.

로컬 루프에서 CI로

Hermes가 시나리오를 로컬에서 실행하고 종료 코드에 따라 조치하면, 파이프라인이 사용할 정확한 명령을 검증한 것입니다. CI로의 전환은 간단합니다: 동일한 `apidog run` 명령을 사용하되, 토큰은 저장된 로그인 대신 마스킹된 비밀(secret)로 전달됩니다. Hermes는 컨텍스트 파일에서 명령을 알고 있으므로, Hermes에게 단계를 작성하도록 요청하세요:

apidog-cli를 설치하고 `apidog run -t 605067 -e 1629989 -r junit`을 실행하며, `APIDOG_ACCESS_TOKEN`이라는 저장소 비밀(secret)에서 액세스 토큰을 읽는 GitHub Actions 단계를 작성해 주세요.

해당 단계의 메커니즘(비밀, 리포터, 종료 코드 게이팅)은 GitHub Actions의 Apidog CLI에 있습니다. 동일한 명령이 터미널, Hermes의 루프, CI 세 곳에서 모두 하나의 종료 코드를 기반으로 실행됩니다.

일반적인 문제점

Hermes가 컨텍스트 블록을 무시합니다. Hermes가 일반적인 명령을 실행하거나 아무것도 실행하지 않는다면, 파일 이름이 정확히 `AGENTS.md` (또는 `CLAUDE.md`)이고 Hermes가 시작된 디렉터리에 있는지 확인하세요. 세션을 다시 시작하면 새로 읽어옵니다.
명령을 실행하는 대신 제안만 합니다. Hermes는 승인 계층 뒤에 있는 `terminal` 도구를 통해 명령을 실행합니다. 대기 중인 실행을 승인하세요. 구성이 터미널 명령을 거부하는 경우, `apidog run`에 대한 권한을 완화하세요.
`apidog whoami`가 인증되지 않았다고 표시합니다. 로그인은 Hermes가 아닌 사용자 컴퓨터에 저장됩니다. 새 토큰으로 직접 `apidog login --with-token`을 실행한 다음, Hermes에게 `apidog whoami`로 확인하도록 요청하세요. 토큰은 채팅에 노출하지 마세요.
플래그를 만들어냅니다. "알 수 없는 옵션" 오류는 Hermes가 사용자 버전에 없는 플래그를 추측했음을 의미합니다. Hermes에게 `apidog run --help`를 실행하도록 하여 실제 플래그를 복사하세요.
실패한 실행을 통과로 보고합니다. 가장 치명적인 문제이며, 종료 코드 규칙이 `AGENTS.md`와 수동 확인 모두에 포함된 이유입니다. 요약과 종료 코드가 일치하지 않을 때는 코드가 우선합니다.

마무리

Hermes 설정은 하나의 파일과 하나의 습관으로 이루어집니다: 명령, 인증 소스, 종료 코드 규칙을 고정하는 `AGENTS.md` 블록과, Hermes가 `terminal` 도구를 통해 `apidog run`을 실행하도록 하고 직접 종료 코드를 확인하는 습관입니다. `~/.hermes/config.yaml`을 통해 Apidog MCP 서버를 추가하면, 코드를 작성하는 동안 사양을 읽을 수도 있습니다.

여러분은 Apidog에서 시각적으로 시나리오를 계속 작성하고, Hermes는 이를 실행하기만 합니다. 여기서부터 GitHub Actions의 Apidog CLI를 사용하여 동일한 명령을 파이프라인에 연결하거나, 전체 가이드에서 모든 플래그 참조를 읽어볼 수 있습니다.

자주 묻는 질문

Apidog CLI를 사용하기 위해 Hermes 플러그인이 필요한가요?

아니요. Hermes는 `terminal` 도구를 통해 셸 명령을 실행하므로, `apidog run`을 직접 호출합니다. 유일한 Hermes 관련 설정은 `AGENTS.md` 블록과 선택적인 MCP 서버입니다.

Hermes에게 워크플로우를 가르치는 지침은 어디에 두어야 하나요?

Hermes가 시작 시 로드하는 컨텍스트 파일에 넣습니다. Hermes의 컨텍스트 엔진은 작업 디렉터리에서 `AGENTS.md` 및 `CLAUDE.md`와 같은 파일을 스캔하여 시스템 프롬프트에 주입합니다. Apidog 블록을 저장소 루트의 `AGENTS.md`에 두면 해당 저장소의 모든 세션이 이를 읽습니다.

Hermes가 테스트 통과를 속이지 않도록 하려면 어떻게 해야 하나요?

요약뿐만 아니라 종료 코드를 보고하도록 하고, 그 코드를 직접 확인하세요. `apidog run`은 모든 단언이 통과할 때만 `0`으로 종료합니다. 설명과 코드가 일치하지 않을 때는 코드를 신뢰하세요.

Apidog MCP 서버를 Hermes에 연결하려면 어떻게 해야 하나요?

`apidog-mcp-server` 명령과 프로젝트 ID를 사용하여 `~/.hermes/config.yaml`에 `mcp_servers` 항목을 추가한 다음, `/reload-mcp`를 실행하거나 Hermes를 다시 시작하세요. Hermes는 시작 시 서버를 검색하고 해당 도구를 등록합니다. Apidog MCP 서버 가이드는 프로젝트 ID 및 토큰에 대해 다룹니다.

다른 AI 코딩 에이전트에서도 동일하게 작동하나요?

CLI는 어디서나 동일하게 작동하며, 에이전트에게 지시하는 방식만 다릅니다. Hermes는 `AGENTS.md`를 읽고 `terminal` 도구를 통해 명령을 실행합니다. 다른 에이전트는 자체 지시 파일을 사용합니다. 설치 및 인증은 동일하므로, 설치 가이드는 모든 에이전트에 적용됩니다.