gmp-cli

gmp-cli란?

gmp-cli는 Google Marketing Platform 서비스를 다루는 명령줄 인터페이스로, GA4 (Google Analytics Data API), Google Search Console, Google Ads, Google Tag Manager를 포함합니다. 핵심 목적은 웹 UI를 통해 수동으로 작업하는 대신 터미널(또는 스크립트)에서 마케팅 데이터와 설정 세부 정보를 가져오는 것입니다.

이 프로젝트는 “에이전트 친화적” 워크플로를 염두에 두고 제작되었습니다: JSON 출력을 jq 같은 도구로 파이핑할 수 있어 결과를 AI 에이전트에 직접 전달하거나 쉘 스크립트에서 처리할 수 있습니다.

주요 기능

여러 GMP 서비스를 위한 통합 CLI: GA4, Search Console, Google Ads, Tag Manager는 전용 서브커맨드를 통해 접근합니다.
인증 및 토큰 관리: OAuth 기반 로그인을 지원하며, 토큰은 ~/.config/gmp-cli/tokens.json에 저장되고 자동 새로고침됩니다.
GA4 보고 및 필터링: 메트릭/차원(예: 페이지 경로별 세션 및 이탈률)에 대한 보고서를 날짜 범위와 값 필터로 실행합니다.
Search Console 분석 + 인덱스 검사: 검증된 사이트 목록, 검색 분석 보고서 생성, URL 인덱싱 검사, 사이트맵 목록.
Google Ads 성과 쿼리: 접근 가능한 계정 목록(MCC 옵션), 캠페인/광고 그룹/키워드/검색어 검색, 원시 GAQL 쿼리 실행.
Tag Manager 워크스페이스 작업: 계정/컨테이너 목록, 태그/트리거/변수 목록, 게시된 버전 검색(특정 워크스페이스 선택 포함).
구조화된 출력 형식: 명령어는 -f / --format을 지원(예: GA4 보고서의 테이블 또는 CSV)하여 스크립트에서 활용 가능합니다.

gmp-cli 사용법

CLI 설치 (저장소에서):
- git clone https://github.com/lucianfialho/gmp-cli.git
- cd gmp-cli
- npm install
- npm run build
- npm link
OAuth 인증 설정 (첫 번째만):
- Google Cloud Console에서 프로젝트 생성.
- 필요한 API 활성화 (Analytics Data API, Analytics Admin API, Search Console API, Google Ads API).
- OAuth 동의 화면 구성 및 Desktop app용 OAuth Client ID 생성.
- 리디렉트 URI: http://localhost:3847/callback.
- 인증 실행:
  - gmp auth set-credentials --client-id YOUR_ID --client-secret YOUR_SECRET
  - gmp auth login
  - gmp auth status
서비스별 자격 증명 추가:
- Google Ads: gmp auth set-developer-token YOUR_DEVELOPER_TOKEN으로 개발자 토큰 설정.
- Manager Account (MCC) 사용 시: gmp auth set-login-customer-id 1234567890으로 로그인 고객 ID 설정.
보고서 실행 및 결과 내보내기 관련 명령어 그룹 사용(예: gmp ga, gmp gsc, gmp ads, gmp gtm). -f로 출력 형식 제어, 필요 시 CSV 출력을 파일로 리디렉션.

사용 사례

터미널에서 주간 GA4 성과 검토: 지난 30일 pagePath별 세션 및 이탈률 생성 후 CSV로 내보내 스프레드시트 검토.
필터 적용 GA4 분석: 동일 GA4 보고서 실행하되 특정 페이지 경로(예: pagePath==/product)로 제한하고 사용자 지정 날짜 범위 설정.
Search Console 쿼리 모니터링: 지난 28일 검증 사이트 상위 쿼리 목록 또는 특정 쿼리 키워드로 결과 필터링.
Google Ads 성과 보고 (이해관계자용): 날짜 범위 캠페인 목록 및 캠페인/광고 그룹/키워드 성과 테이블 검색; GAQL로 사용자 지정 메트릭 쿼리 선택적 사용.
Tag Manager 재고 및 감사: 특정 컨테이너/워크스페이스 태그, 트리거, 변수 목록 및 게시된 버전 검토.

자주 묻는 질문

OAuth 토큰은 어디에 저장되나요?

토큰은 ~/.config/gmp-cli/tokens.json에 저장되며 자동 새로고침됩니다.

Google Ads 개발자 토큰이 필요하나요?

네. 프로젝트의 Google Ads API 설정에 OAuth 자격 증명 외 developer token이 필요합니다.

스크립팅을 위한 결과 출력은 어떻게 하나요?

많은 명령어가 -f / --format으로 출력 제어. GA4 보고서는 README에서 table 또는 csv 출력 예시와 CSV 파일 리디렉션 시연.

MCC를 통한 Google Ads 쿼리가 가능하나요?

README에 gmp auth set-login-customer-id를 통한 MCC 설정과 MCC 옵션 Ads 계정 목록 명령어 포함.

CLI가 “에이전트 친화적” 워크플로를 어떻게 지원하나요?

프로젝트는 JSON 출력을 jq 같은 도구로 파이핑해 AI 에이전트에 공급하거나 쉘 스크립트에서 사용하도록 명시적으로 지원합니다.

대안

Google의 공식 API (직접 호출): CLI 래퍼 대신 코드에서 API를 직접 사용할 수 있습니다. 최대 유연성을 제공하지만 인증 및 요청 로직을 직접 구축해야 합니다.
기타 데이터 추출 스크립팅 접근법: REST/공식 클라이언트 라이브러리를 통해 Google 서비스를 호출하고 결과를 JSON/CSV로 포맷하는 스크립트를 작성할 수 있습니다. 자동화 목표는 유사하지만 즉시 사용 가능한 명령 구조가 없습니다.
Tag Manager/GMP 웹 인터페이스: 일회성 확인에는 내장 UI가 더 간단할 수 있습니다. 하지만 CLI에 비해 반복 가능하고 스크립팅 가능한 워크플로에는 덜 적합합니다.
Analytics/리포팅 BI 도구: BI 또는 대시보드 도구는 리포팅과 시각화를 중앙화할 수 있습니다. gmp-cli의 터미널 우선 파이핑/자동화 워크플로보다는 대시보드를 강조합니다.