이미 AI 코딩 에이전트가 열려 있습니다. 에이전트는 파일을 편집하고, 테스트를 실행하며, 터미널 출력을 읽습니다. 그런데 왜 탭에서 npm 명령어를 하나씩 복사하여 붙여넣으면서 명령줄 도구를 수동으로 설치하려고 하시나요?
그럴 필요 없습니다. Apidog CLI는 터미널에서 Apidog에 구축한 API 테스트 시나리오를 직접 실행하는 apidog-cli라는 npm 패키지입니다. 설치는 짧은 셸 명령어 시퀀스, 인증 단계, 그리고 첫 실행으로 이루어집니다. 이는 Claude Code, Cursor, Windsurf 또는 에이전트 모드의 GitHub Copilot과 같은 에이전트가 잘 수행하는 기계적인 작업의 정확한 유형입니다. 목표를 설명하면 에이전트가 실제 명령을 실행하고, 사용자는 에이전트의 작업을 확인합니다.
이 가이드에서는 이 워크플로우를 처음부터 끝까지 보여줍니다. 에이전트에 전달할 정확한 프롬프트, 에이전트가 실행할 명령, 그리고 에이전트의 말을 그대로 믿는 대신 각 단계를 확인하는 방법을 알 수 있습니다. 마지막의 보상은 설정할 가치가 있는 부분입니다. CLI가 설치되고 인증되면 에이전트가 자체 루프 내에서 또는 CI에서 Apidog 테스트를 직접 실행하고 통과 또는 실패 결과를 읽을 수 있습니다. 따라 하려면 하나 이상의 프로젝트가 있는 Apidog 계정이 필요합니다. 아직 계정이 없다면 먼저 Apidog를 다운로드하세요.
에이전트가 설치를 수행하도록 해야 하는 이유
에이전트가 실행하더라도 설치 명령은 아무것도 달라지지 않습니다. 직접 입력하는 것과 동일한 npm install -g apidog-cli@latest입니다. 달라지는 것은 누가 입력하고 누가 출력을 읽느냐입니다.
에이전트가 이 작업을 잘하는 세 가지 구체적인 이유가 있습니다. 에이전트는 명령을 실행하고, 종료 상태와 출력된 텍스트를 읽고, 실제로 본 내용에서 다음 단계를 결정할 수 있으므로, '명령을 찾을 수 없음' 오류가 복사-붙여넣기 루프에서처럼 작업을 중단시키지 않습니다. 에이전트는 이미 사용자의 셸, Node 버전, PATH를 파악하고 있으므로 일반적인 수정 대신 사용자의 머신에 맞는 수정을 적용합니다. 그리고 Node를 먼저 확인하고, 설치 후 버전을 확인하고, 인증을 확인하는 등 사용자가 각 라인을 일일이 감독하지 않아도 지루한 부분을 처리합니다.
시작하기 전에 필요한 것
CLI는 npm 패키지로 제공되므로 유일한 시스템 종속성은 Node.js 런타임입니다. 다음 세 가지가 충족되어야 합니다.
- Node.js와 npm이 설치되어 있어야 합니다. 패키지는 npm을 통해 설치되며 Node에서 실행됩니다. 현재 LTS 릴리스는 모든 개발자 머신에서 안전한 선택입니다.
- 프로젝트 접근 권한이 있는 Apidog 계정. CLI는 자체 테스트를 저장하지 않습니다. Apidog 프로젝트에 접근하여 해당 프로젝트에 있는 시나리오를 실행하므로, 하나 이상의 프로젝트를 볼 수 있는 계정이 필요합니다.
- 실행할 테스트 시나리오. 러너는 개별 요청이 아닌 시나리오를 실행합니다. Apidog 앱에서 먼저 시나리오를 만드세요: 몇 가지 요청을 연결하고, 어설션을 추가하고, 저장합니다. 응답에 대한 검증 작성이 처음이라면, API 어설션: 실용 가이드에서 자세히 설명합니다.
또한 셸 명령을 실행할 권한이 있는 AI 코딩 에이전트가 필요합니다. Claude Code, Cursor의 에이전트, Windsurf의 Cascade, 그리고 GitHub Copilot의 에이전트 모드가 모두 해당됩니다. 시작하기 전에 확인해야 할 한 가지는 에이전트가 명령을 제안하는 것뿐만 아니라 터미널에서 명령을 실행할 수 있도록 허용되어 있는지 여부입니다. 에이전트가 붙여넣을 명령만 출력할 수 있다면 이 가이드를 계속 따를 수 있지만, 엔터 키를 누르는 것은 사용자가 됩니다.
1단계: 에이전트가 환경 확인하도록 하기
먼저 에이전트가 Node가 있는지 확인하도록 하여 설치 가능 여부를 알 수 있도록 합니다. 다음과 같은 프롬프트가 효과적입니다.
이 머신에 Node.js와 npm이 설치되어 있는지 확인하세요.node -v와npm -v를 실행하고 버전을 알려주세요. 둘 중 하나라도 없으면 저에게 알려주시고, 직접 Node를 설치하려고 시도하지 마세요.
에이전트가 다음을 실행합니다.
node -v
npm -v
에이전트는 두 가지 버전 번호를 다시 보고해야 합니다. 사용자 확인: 에이전트가 출력하는 버전을 읽으세요. Node가 설치되어 있다고 주장하지만 버전 문자열을 보여주지 않는다면, 원시 명령 출력을 붙여넣도록 요청하세요. 프롬프트에서 '직접 Node를 설치하지 마세요'라는 문구를 넣은 이유는 런타임 설치가 의도적으로 결정해야 하는 더 크고 머신별 결정이지, 맹목적으로 맡길 일이 아니기 때문입니다. Node가 없다면 nodejs.org에서 직접 설치한 다음 계속 진행하세요.
2단계: 에이전트가 CLI를 설치하도록 하기
Node가 확인되면 설치를 맡기세요.
https://apidog.com/apidog-cli-installation-guide.md를 읽고 지침을 따르세요.
에이전트가 설치 명령을 실행합니다.
-g 플래그는 apidog 바이너리를 하나의 프로젝트 node_modules 대신 전역 PATH에 배치합니다. @latest 태그는 최신 게시 버전을 가져오는데, 이는 첫 설치에 필요한 것입니다. npm이 완료되면 바이너리 이름은 apidog가 되므로, 이제부터 모든 명령은 apidog로 시작합니다.
그 다음 에이전트가 확인합니다.
apidog --version
apidog --help
사용자 확인: 이 과정에서 가장 중요한 검증입니다. 에이전트가 얻지 못한 성공을 주장하기 가장 쉬운 곳이기 때문입니다. apidog --version이 에이전트가 무시하고 지나간 '명령을 찾을 수 없음'이 아닌 실제 버전 번호를 출력했는지 확인하세요. --help 출력에는 apidog run과 그 옵션이 나열되어야 합니다. 바이너리와 그 뒤에 있는 런타임이 모두 해결되었는지 직접 확인할 수 있는 한 줄 명령어를 원한다면, 에이전트에게 다음 명령을 실행하고 결과를 붙여넣도록 요청하세요.
node -v && apidog --version && which node && which apidog
모든 줄이 버전 또는 경로를 반환하면 설치가 깨끗하게 완료된 것입니다. 에이전트가 문제가 있다고 보고하면, 가장 흔한 원인은 전역 bin 디렉토리가 PATH에 없는 경우이며, 이는 끝 부분의 문제 해결 섹션에서 다룹니다.
에이전트가 전역 패키지를 변경하지 않기를 원한다면, 대신 npx를 사용하도록 지시하세요. npx apidog-cli --version은 패키지를 가져와 실행하고 PATH에 아무것도 남기지 않으므로, 공유 머신이나 임시 CI 러너에 적합합니다. 매일 사용하는 머신의 경우, 전역 설치가 반복 호출 시 더 간단하고 빠릅니다.
3단계: 에이전트가 인증하도록 하되, 토큰은 사용자가 처리
CLI는 사용자 계정에서 시나리오를 실행하므로, 허용되었음을 증명해야 합니다. 이는 액세스 토큰으로 수행됩니다. 토큰은 비밀이므로 채팅 기록, 로그 파일 또는 에이전트가 다시 에코할 수 있는 어떤 곳에도 붙여넣고 싶지 않기 때문에 이 단계는 완전히 위임하지 않습니다.
먼저 토큰을 직접 생성하세요. Apidog 앱 또는 웹 콘솔을 열고, 사용자 아바타를 클릭한 다음 계정 설정으로 이동하여 API 액세스 토큰에서 새 토큰을 생성하세요. 안전한 곳에 복사하고 비밀번호처럼 다루세요. 이 토큰을 가진 사람은 누구든지 사용자로서 시나리오를 실행할 수 있기 때문입니다.
그런 다음 프롬프트에 토큰을 절대 넣지 않고 에이전트에게 프롬프트를 전달하세요.
Apidog CLI를 직접 인증하여 토큰이 이 채팅에서 벗어나도록 하겠습니다. 실행할 정확한apidog login명령을 알려주세요. 제가 실행했음을 확인한 후,apidog whoami를 실행하여 CLI가 인증되었는지 확인하고 결과를 보여주세요.
터미널에서 로그인 명령을 직접 실행합니다.
apidog login --with-token YOUR_ACCESS_TOKEN
에이전트가 확인을 실행하도록 하세요.
apidog whoami
사용자 확인: apidog whoami는 사용자 계정을 출력해야 합니다. 출력되면 인증이 설정된 것입니다. 토큰을 직접 관리하는 이유는 간단한 운영 위생 때문입니다. 에이전트의 컨텍스트 창에 들어간 토큰은 로그 또는 저장된 기록에 남을 수 있습니다. 로그인 명령은 토큰을 로컬 머신에 저장하므로, 에이전트가 나중에 테스트를 실행하기 위해 원본 문자열을 볼 필요가 없습니다. CI의 경우 규칙은 동일하지만 더 엄격하며, 이는 마지막 섹션에서 다룹니다.
4단계: 에이전트가 첫 번째 테스트 실행하도록 하기
이제 '설치됨'에서 '실제로 실행됨'으로 넘어갑니다. 핵심 명령은 ID로 시나리오를 가리키는 apidog run입니다.
정확한 명령을 얻는 가장 깔끔한 방법은 Apidog가 명령을 생성하도록 하는 것입니다. Apidog에서 테스트 시나리오를 열고, CI/CD 탭으로 전환하고, 명령줄 옵션을 선택하면 Apidog가 시나리오 ID, 환경 ID, 액세스 토큰이 이미 채워진 완전한 apidog run 명령을 생성합니다. 이를 복사하면 유효성이 보장된 시작점을 얻게 됩니다. 다음과 같습니다.
apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli
각 부분이 하는 일은 다음과 같습니다. --access-token은 실행을 인증합니다. -t는 ID로 테스트 시나리오를 지정합니다(605067은 플레이스홀더이며, 실제 ID는 다를 것입니다). -e는 개발 또는 스테이징과 같이 실행할 환경을 선택합니다. -n 1은 시나리오를 한 번 실행합니다. -r cli는 터미널에 읽기 쉬운 보고서를 작성합니다.
이미 로그인했으므로 토큰 없이 ID를 에이전트에게 전달하고 실행하도록 할 수 있습니다.
CLI로 Apidog 테스트 시나리오를 실행하세요. 이미 인증되었으므로 액세스 토큰을 전달하지 마세요. 다음을 사용하세요: apidog run -t 605067 -e 1629989 -n 1 -r cli. 전체 출력을 보여주고 종료 코드를 알려주세요.에이전트가 시나리오를 실행하고 단계별 실행과 요약을 보고할 것입니다. 사용자 확인: 종료 코드를 명시적으로 요청하세요. 이는 모든 다운스트림이 의존하는 신호이기 때문입니다. apidog run은 모든 어설션이 통과하면 0으로 종료하고, 무언가 실패하면 0이 아닌 코드로 종료합니다. 이 단일 동작 덕분에 파이프라인이나 에이전트가 추가적인 연결 없이 실행을 깔끔한 통과 또는 실패 게이트로 처리할 수 있습니다. 에이전트가 '테스트 통과'라고 말했지만 종료 코드가 0이 아니었다면, 그것은 잘못된 것이므로 설명이 아닌 코드를 믿으세요.
다른 보고서 형식이나 더 많은 반복을 원하십니까? 에이전트에게 apidog run --help를 실행하도록 하세요. 이 명령은 다른 리포터와 데이터 기반 반복 옵션을 포함하여 러너가 지원하는 모든 플래그를 출력합니다. 전체 플래그 참조 및 CI 예시는 전체 Apidog CLI 가이드에서 각 항목을 다룹니다.
그 결과: 이제 에이전트가 자체적으로 테스트할 수 있습니다
설정이 가치 있었던 이유가 여기에 있습니다. CLI가 설치되고 인증되면, Apidog 테스트를 실행하는 것은 이제 에이전트가 언제든지 실행하고 결과를 읽을 수 있는 단일 셸 명령이 됩니다. 이는 API 테스트를 에이전트의 일반적인 루프에 통합합니다.
에이전트가 엔드포인트를 건드리는 핸들러를 변경하는 상황을 상상해보세요. 코드를 편집하고 성공을 선언하는 대신, 에이전트는 영향을 받는 환경에 대해 Apidog 시나리오를 실행하고, 종료 코드를 읽고, 이에 따라 조치할 수 있습니다. 녹색이면 다음으로 진행하고, 빨간색이면 보고서에서 실패한 어설션을 읽고 수정하려고 시도합니다. 테스트는 에이전트의 피드백 루프의 일부가 되며, 에이전트가 이미 단위 테스트를 실행하는 방식과 동일합니다. 이 패턴에 대한 더 넓은 관점을 보려면 API 테스트에 AI 에이전트를 사용하는 방법에서 이 패턴이 어디에 적합하고 어디에 적합하지 않은지 다룹니다.
이는 에이전트가 존재하지 않는 CI로 직접 이어집니다. 명령이 로컬에서 작동하는 것을 확인하면, 에이전트가 모든 푸시에서 명령을 실행하는 파이프라인 단계를 작성하도록 할 수 있습니다. 그 메커니즘, 비밀, 리포터, 종료 코드 게이팅은 GitHub Actions의 Apidog CLI에 있습니다.
에이전트 통합이 셸 명령 실행보다 더 깊이 들어가기를 원한다면, 두 가지 Apidog 기능이 에이전트를 API 사양 및 시나리오에 더 직접적으로 연결합니다. Apidog MCP 서버는 Model Context Protocol을 통해 AI 코딩 도구에 API 사양을 노출하므로, 에이전트가 코딩하는 동안 스키마를 읽을 수 있습니다. 그리고 Claude Skills가 포함된 Apidog CLI는 CLI 워크플로우를 재사용 가능한 기술로 패키징하므로, 테스트 실행 단계가 Claude가 스스로 찾는 것이 됩니다. 이 두 기능 모두 방금 설정한 동일한 설치된 apidog-cli 위에 구축됩니다.
위임된 설치에서 테스트 루프까지
이것이 전체 과정입니다. Node를 확인하고, 에이전트가 하나의 npm 명령으로 apidog-cli를 설치하며, apidog --version으로 확인하고, 직접 보관한 토큰으로 인증한 다음, 사용자가 종료 코드를 확인하는 동안 에이전트가 첫 번째 apidog run을 실행합니다. 몇 분간의 위임-확인 과정을 거치면 이제 에이전트가 자체적으로 API 테스트를 실행할 수 있습니다.
이것이 중요한 이유는 모든 테스트 게이트가 중요한 이유와 같지만, 한 가지 추가 사항이 있습니다. GUI 뒤에 갇힌 테스트는 사람이 클릭할 때만 실행됩니다. 한 줄 명령은 모든 푸시에서 실행됩니다. 그리고 그 명령이 코딩 에이전트의 손이 닿는 곳에 있게 되면, 아직 검토하지 않은 변경 사항에 대해 에이전트 자체의 편집-테스트-수정 루프 내에서 실행됩니다. Apidog에서 시나리오를 시각적으로 계속 작성하면, 파이프라인과 에이전트 모두 사람이 지켜보지 않는 곳에서 시나리오를 실행합니다.
여기서부터, 동일한 명령을 GitHub Actions의 Apidog CLI에서 CI로 지정하거나, 전체 Apidog CLI 가이드에서 전체 플래그 참조를 읽어보세요.