DEV Community

Cover image for Apidog CLI: 터미널 기반 API 클라이언트
Rihpig
Rihpig

Posted on Originally published at apidog.com

Apidog CLI: 터미널 기반 API 클라이언트

API 워크스페이스는 GUI에 있고, 실제 업무는 터미널에서 이루어지는 경우가 많습니다. 이 컨텍스트 전환은 집중력을 끊고, CI 파이프라인이나 AI 에이전트 세션에서는 GUI를 사용할 수조차 없습니다. Apidog CLI는 셸에서 테스트, 엔드포인트, 스키마, 환경, 모의 기대치, 문서를 다룰 수 있게 해 이 간극을 줄입니다.

지금 Apidog 사용해 보기

먼저 역할을 명확히 하겠습니다. Apidog CLI는 또 다른 curl이 아닙니다. 단일 GET 요청을 보내고 응답 JSON을 확인하려면 curl, HTTPie 또는 터미널 및 TUI REST 클라이언트를 사용하세요.

Apidog CLI는 API 워크스페이스를 위한 CLI 클라이언트입니다. 시각적 편집기에서 만든 테스트 시나리오를 실행하고, API 계약을 읽거나 수정하며, 스펙을 가져오고 내보내는 작업에 적합합니다.

여기서 “터미널에 상주한다”는 의미

일반적인 터미널 HTTP 도구는 요청 단위로 동작합니다. Apidog CLI는 프로젝트 단위로 동작하며, 명령은 크게 다음 작업으로 나뉩니다.

작업 주요 명령
테스트 실행 run, test-scenario, test-suite, test-case, test-data, test-report
계약 관리 endpoint, schema, folder, common-parameter, response-component, security-scheme
문서 및 모의 배포 doc, docs-site, shared-doc, mock
구성 및 연결 environment, variables, vault, database-connection, websocket, socketio
팀 운영 branch, merge-request, runner, scheduled-task, audit-log, import, export

명령 사용법은 항상 --help로 확인할 수 있습니다.

apidog run --help
apidog endpoint --help
Enter fullscreen mode Exit fullscreen mode

명령 결과는 구조화된 JSON으로 출력되며, 대부분의 응답에는 다음 작업을 안내하는 agentHints.nextSteps가 포함됩니다. 따라서 스크립트나 에이전트는 결과를 파싱한 뒤 다음 명령을 결정할 수 있습니다.

설치 및 인증

Apidog CLI는 npm 패키지로 제공되며 macOS, Linux, Windows에서 실행됩니다. Node.js 16 이상이 필요합니다.

npm install -g apidog-cli
apidog --version
Enter fullscreen mode Exit fullscreen mode

설치 후 API 액세스 토큰으로 로그인합니다. Apidog 앱에서 아바타를 클릭한 뒤 계정 설정 → API 액세스 토큰에서 토큰을 복사합니다.

apidog login --with-token <YOUR_TOKEN>
Enter fullscreen mode Exit fullscreen mode

로그인 토큰은 ~/.apidog/config.toml에 저장됩니다. 이 파일이나 토큰 값이 저장소와 로그에 노출되지 않도록 주의하세요.

CI에서는 저장된 로그인 대신 시크릿을 --access-token으로 전달하는 방식이 적합합니다.

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenario_id> \
  -e <env_id> \
  -r cli
Enter fullscreen mode Exit fullscreen mode

자주 사용하는 전역 옵션은 다음과 같습니다.

옵션 용도
--project 대상 프로젝트 선택
--branch 대상 브랜치 선택
--access-token 저장된 로그인 대신 토큰 직접 지정
--api-base-url 자체 호스팅 Apidog 배포 지점 지정

토큰 기반 CI 인증은 Apidog CLI 인증 가이드에서 더 자세히 확인할 수 있습니다.

시각적으로 만든 테스트를 CI에서 실행하기

기본 워크플로우는 다음과 같습니다.

  1. Apidog 시각적 편집기에서 테스트 시나리오를 작성합니다.
  2. 요청 간 변수 전달, 응답 추출, 상태 코드 및 본문 어설션을 구성합니다.
  3. 시나리오의 CI/CD 탭에서 실행 명령과 ID를 복사합니다.
  4. 로컬 셸 또는 CI에서 실행합니다. 
apidog run -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

모든 어설션이 통과하면 프로세스는 종료 코드 0을 반환합니다. 실패하면 0이 아닌 코드로 종료되므로, 별도 접착 코드 없이 CI 단계의 성공 여부를 제어할 수 있습니다.

환경만 바꿔 같은 시나리오를 개발, 스테이징, 프로덕션에 실행할 수 있습니다.

# 개발 환경
apidog run -t <scenario_id> -e <dev_env_id> -r cli

# 스테이징 환경
apidog run -t <scenario_id> -e <staging_env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

CSV 또는 JSON 테스트 데이터를 제공하면 각 행 또는 항목에 대해 시나리오를 반복 실행할 수 있습니다. 테스트 단계를 복제하지 않고 입력 데이터만 바꾸려면 데이터 기반 테스트를 사용하세요.

처음부터 실행 흐름을 구성한다면 단계별 REST API 가이드를 참고할 수 있습니다.

보고서 생성하기

-r 옵션으로 보고서 형식을 지정합니다.

  • cli: 터미널에 단계별 결과 출력
  • html: HTML 보고서 생성
  • json: JSON 보고서 생성
  • junit: CI 도구용 JUnit 보고서 생성

html, json, junit 보고서는 apidog-reports/ 디렉터리에 저장됩니다. 형식은 함께 지정할 수 있습니다.

apidog run \
  -t <scenario_id> \
  -e <env_id> \
  -r cli,junit
Enter fullscreen mode Exit fullscreen mode

형식별 결과는 테스트 보고서 가이드에서 확인할 수 있습니다.

로컬 노트북에 의존하지 않는 실행이 필요하다면 runner와 scheduled-task 명령으로 자체 호스팅 러너 및 예약 실행을 관리할 수 있습니다. 이는 Apidog에서 API 테스트 예약과 같은 방식으로 동작합니다.

앱을 열지 않고 API 계약 관리하기

Apidog CLI는 테스트 실행뿐 아니라 API 정의도 읽고 수정할 수 있습니다.

# 프로젝트의 엔드포인트 조회
apidog endpoint list --project <project_id>

# 스키마 조회
apidog schema get <schema_id>

# 환경 목록 조회
apidog environment list

# 모의 기대치 조회
apidog mock list
Enter fullscreen mode Exit fullscreen mode

다음 리소스를 CLI에서 조회하거나 편집할 수 있습니다.

  • 엔드포인트
  • 데이터 스키마
  • 폴더
  • 환경 및 변수
  • 보안 스키마
  • 재사용 가능한 응답 구성 요소
  • 데이터베이스 연결
  • WebSocket 및 Socket.IO 엔드포인트
  • 문서 사이트 및 공유 문서
  • 모의 기대치

mock 명령은 모의 서버가 반환할 고정 요청-응답 쌍을 관리합니다. doc 및 docs-site 명령은 게시 문서를 다룹니다.

OpenAPI 및 Postman 컬렉션 마이그레이션

가져오기와 내보내기는 다음 형식을 지원합니다.

  • OpenAPI 3.x
  • Swagger 2.0
  • Postman 컬렉션

OpenAPI와 Swagger는 많은 도구 체인이 표준화하는 사양입니다. CLI를 사용하면 스펙을 가져오고 Apidog 프로젝트에 반영한 뒤, 내보낸 결과를 버전 관리 흐름에 포함할 수 있습니다.

# OpenAPI 파일 가져오기
apidog import openapi.json --project <project_id>

# OpenAPI 형식으로 내보내기
apidog export --format openapi
Enter fullscreen mode Exit fullscreen mode

AI 에이전트가 안전하게 작업하도록 구성하기

2026년 CLI 릴리스는 AI 코딩 에이전트가 API 워크스페이스를 안전하게 운영할 수 있도록 설계되었습니다. 핵심은 다음 네 가지입니다.

1. 구조화된 JSON 출력

모든 명령은 에이전트가 파싱할 수 있는 JSON을 반환합니다. agentHints.nextSteps는 명령 결과 이후 수행할 작업과 오류 복구 방향을 안내합니다.

2. 입력 스키마 조회 및 검증

쓰기 명령을 실행하기 전에 해당 명령이 기대하는 JSON 형식을 확인할 수 있습니다.

# 사용 가능한 CLI 입력 스키마 조회
apidog cli-schema list

# 특정 스키마 조회
apidog cli-schema get <schema_id>

# 작성한 페이로드 검증
apidog cli-schema validate <payload.json>
Enter fullscreen mode Exit fullscreen mode

에이전트 또는 자동화 스크립트의 안전한 쓰기 절차는 다음 순서로 구성하세요.

  1. cli-schema get으로 입력 스키마를 가져옵니다.
  2. 스키마에 맞춰 JSON 페이로드를 생성합니다.
  3. cli-schema validate로 검증합니다.
  4. 검증이 통과한 경우에만 create 또는 update를 실행합니다.

3. 에이전트용 스킬 제공

skill 명령은 CLI 사용 지식을 에이전트가 직접 로드할 수 있는 형태로 제공합니다. Apidog CLI 스킬은 이 목적을 위해 제공됩니다.

자체 측정 결과에 따르면, CLI 스키마를 통해 작업하는 에이전트는 페이로드를 추측하는 방식보다 약 30% 적은 도구 호출과 25% 적은 토큰을 사용했습니다. 측정 방식과 결과는 분석 글에서 확인할 수 있습니다.

4. 권한 게이트와 AI 브랜치

기본적으로 AI 소스의 브랜치 쓰기는 차단됩니다. 사람이 외부 AI 편집 권한을 활성화해야 합니다.

  • Apidog 클라이언트 2.8.32 이상
  • 프로젝트 설정
  • 기능 설정
  • AI 기능 설정

또는 AI 브랜치를 사용할 수 있습니다. AI 브랜치는 에이전트가 필요한 리소스를 가져오고 수정한 뒤, 병합 요청으로 사람에게 검토를 요청하는 격리 브랜치입니다. 수정되지 않은 AI 브랜치는 24시간 후 자동 보관됩니다.

즉, 에이전트가 계약 초안을 작성하더라도 최종 변경 사항은 검토 가능한 상태로 유지됩니다.

Apidog CLI가 아닌 것

도구 선택 전에 다음 한계를 확인하세요.

상호작용형 요청 클라이언트가 아닙니다

임시 POST 요청을 작성하고 응답을 보기 좋게 출력하는 용도는 아닙니다. 그런 작업에는 curl, HTTPie, TUI 클라이언트가 더 적합합니다.

오픈 소스가 아닙니다

패키지는 독점 소프트웨어이며 npm이 유일한 설치 채널입니다. --help 이상의 기능을 사용하려면 Apidog 계정이 필요합니다. 무료 티어에는 여기서 설명한 시나리오 작성 및 CLI 실행 워크플로우가 포함되지만, 감사 가능한 라이선스가 필수라면 오픈 소스 러너를 검토하는 편이 적합합니다.

독립형 도구가 아닙니다

CLI는 Apidog 플랫폼의 터미널 인터페이스입니다. 시나리오, 엔드포인트, 환경은 로컬 파일이 아니라 Apidog 프로젝트에 있습니다. 대신 설계, 테스트, 모의, 문서 전반에서 하나의 진실 공급원을 유지할 수 있습니다.

터미널 도구 상자에서의 위치

도구마다 테스트 작성 방식이 다릅니다.

도구 일반적인 작성 방식
Newman, Postman CLI Postman 컬렉션 실행
Hurl, Bruno 텍스트 파일 기반 테스트 실행
Apidog CLI 시각적 편집기에서 만든 시나리오 실행

Apidog CLI 시나리오는 계약, 모의, 문서와 같은 프로젝트 리소스와 연결됩니다. 자세한 비교는 Apidog CLI와 Newman 비교 및 최고의 터미널 기반 API 테스트 도구에서 확인할 수 있습니다.

실무에서는 다음처럼 역할을 나누는 것이 좋습니다.

  • 임시 요청: curl 또는 xh
  • 저장된 API 시나리오와 CI: apidog run
  • 계약, 환경, 문서, 모의 리소스 관리: Apidog CLI 명령 그룹

GitHub Actions 가이드에는 복사해서 사용할 수 있는 파이프라인 예제가 포함되어 있습니다.

자주 묻는 질문

Apidog CLI는 무료로 사용할 수 있나요?

네. npm에서 무료로 설치할 수 있으며, Apidog 무료 티어에는 시나리오 작성과 CLI 실행이 포함됩니다. 유료 플랜은 기본 CLI 접근 자체가 아니라 팀 규모 기능을 추가합니다.

curl 또는 HTTPie를 대체하나요?

아니요. curl과 HTTPie는 임시 요청에 적합하고, Apidog CLI는 저장된 테스트 시나리오 실행 및 프로젝트 리소스 관리에 적합합니다. 대부분의 터미널 환경에서는 두 종류의 도구를 함께 사용하게 됩니다.

CI에서 완전히 헤드리스로 실행할 수 있나요?

네. CI 시크릿의 --access-token으로 인증하고, 시나리오 ID와 함께 apidog run을 실행한 뒤, 종료 코드로 빌드 결과를 제어하면 됩니다. 러너에 데스크톱 앱은 필요하지 않습니다.

어떤 형식을 가져오고 내보낼 수 있나요?

OpenAPI 3.x, Swagger 2.0, Postman 컬렉션을 양방향으로 지원합니다. 마이그레이션과 통합 흐름에 활용할 수 있습니다.

AI 에이전트는 어떻게 안전하게 사용할 수 있나요?

스키마 조회 → 검증 → 쓰기 절차와 권한 게이트를 사용하세요. cli-schema validate는 잘못된 페이로드를 쓰기 전에 감지하며, AI 브랜치는 사람이 병합할 때까지 에이전트의 변경을 격리합니다. 실제 에이전트 사용 예시는 Claude Code에서 Apidog CLI를 사용하는 방법에서 확인할 수 있습니다.

터미널은 이미 테스트가 실행되고 에이전트가 작업하는 곳입니다. Apidog 다운로드 후 CLI를 설치하고, 먼저 하나의 시나리오를 처음부터 끝까지 실행해 보세요. 이후 전체 명령 참조는 Apidog CLI 페이지에서 확인할 수 있습니다.

Top comments (0)