DEV Community

Cover image for Google Workspace CLI 활용법 및 사용법
Rihpig
Rihpig

Posted on • Originally published at apidog.com

Google Workspace CLI 활용법 및 사용법

#automation #cli #google #tutorial

Google Workspace CLI 소개

Google Workspace CLI(gws로 호출)는 인간과 AI 에이전트 모두에게 Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin 등 모든 Google Workspace API에 통합된 명령줄 액세스를 제공하는 오픈 소스 도구입니다. 이 도구는 Google의 실시간 Discovery Service를 기반으로 하며, 별도의 업데이트 없이 항상 최신 명령을 사용할 수 있습니다. npm으로 전역 설치 후 OAuth로 인증하면, Claude Code, Cursor 등 다양한 에이전트에 손쉽게 연결 가능합니다. 별도 SDK나 복잡한 OAuth 흐름 없이 바로 활용할 수 있습니다.

지금 Apidog를 사용해보세요

Google Workspace CLI가 필요한 이유
개발자, 관리자, AI 에이전트 사용자들은 Google Workspace 자동화(예: Drive 파일 관리, Gmail 전송, Calendar 이벤트 생성, Sheets/Docs/Chat 작업)를 원하지만, 직접 curl 스크립트 작성, OAuth 범위 관리, 페이지네이션 처리, SDK 관리 등 각종 번거로움에 부딪힙니다.

Google Workspace의 강력하지만 파편화된 API 구조로 인해, 기존 도구는 API 변경에 쉽게 영향을 받습니다. Google Workspace CLI는 런타임에 실시간 Discovery Service로 API 메서드를 동적으로 제공하며, Rust 기반 CLI로 새로운 엔드포인트도 즉시 지원합니다. 따라서 스크립트와 자동화 작업이 항상 최신 상태를 유지합니다.

주요 특징:

  • 깔끔한 JSON 출력
  • dry-run, 페이지네이션 도우미
  • 40개 이상의 단축키(+ 접두사)
  • Claude Code, Cursor 등 AI 에이전트 연동 스킬 번들 제공

API 통합 및 테스트에는 Apidog 무료 API 클라이언트를 활용하면 요청/응답 점검, 환경 관리, 테스트 자동화가 가능합니다. Google Workspace CLI로 실시간 데이터 액세스, Apidog로 모든 호출의 정상 동작을 검증하세요.

Google Workspace CLI 설치

Node.js 18 이상이 필요합니다. 버전 확인:

node --version
Enter fullscreen mode Exit fullscreen mode

설치 없이 바로 실행

가장 빠른 테스트 방법은 npx를 이용하는 것입니다(항상 최신 버전):

npx @googleworkspace/cli --help
npx @googleworkspace/cli drive files list --params '{"pageSize":1}'
Enter fullscreen mode Exit fullscreen mode

일회성 스크립트나 빠른 테스트에 유용합니다.

전역 설치

정기적으로 사용한다면 전역 설치 후 gws 명령을 사용하세요:

npm install -g @googleworkspace/cli
gws --version
Enter fullscreen mode Exit fullscreen mode

Rust 컴파일 불필요, 미리 빌드된 바이너리 제공. GitHub Releases, Homebrew(brew install googleworkspace/cli), Nix 등도 지원합니다.

AI 코딩 에이전트용 Google Workspace CLI 설정

gws auth setup 명령으로 프로젝트 생성, API 활성화, OAuth 인증까지 한 번에 처리합니다:

gws auth setup
Enter fullscreen mode Exit fullscreen mode

브라우저가 열리며 Google Cloud 프로젝트 생성, API 활성화, 자격 증명(OS 키체인 안전 저장)이 자동으로 진행됩니다.

에이전트 스킬 설치

설정 후 번들 에이전트 스킬을 설치하세요:

npx skills add https://github.com/googleworkspace/cli
Enter fullscreen mode Exit fullscreen mode

또는 에이전트별 설치 프로그램(Claude Code, Cursor 등)을 실행하세요. 에이전트를 재시작하면 Google Workspace CLI 명령을 자동 감지합니다.

프로젝트 수준 설정

기본은 전역 설정이지만, 프로젝트 단위로 구성하려면:

gws auth setup --project
Enter fullscreen mode Exit fullscreen mode

인증 관리

  • 다시 인증/계정 전환: 
  gws auth login
Enter fullscreen mode Exit fullscreen mode
  • 현재 사용자 및 범위 확인: 
  gws auth whoami
Enter fullscreen mode Exit fullscreen mode
  • 로그아웃: 
  gws auth logout
Enter fullscreen mode Exit fullscreen mode

헤드리스/CI 환경

자격 증명 내보내기:

gws auth export --unmasked > creds.json
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/creds.json
Enter fullscreen mode Exit fullscreen mode

또는 gcloud 토큰 사용:

export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
Enter fullscreen mode Exit fullscreen mode

원격 측정 비활성화 

export GOOGLE_WORKSPACE_CLI_NO_TELEMETRY=1
Enter fullscreen mode Exit fullscreen mode

Google Workspace CLI 핵심 명령 실습

명령은 동적으로 제공되므로, 전체 목록은 gws --help로 확인하세요.

Drive 파일 및 폴더

최근 파일 조회:

gws drive files list --params '{"pageSize":10, "q":"name contains report"}'
Enter fullscreen mode Exit fullscreen mode

파일 업로드:

gws drive +upload ./budget.xlsx --name "2026 Budget"
Enter fullscreen mode Exit fullscreen mode

Gmail

이메일 전송:

gws gmail +send --to colleague@example.com --subject "Update" --body "See attached." --attach ./file.pdf
Enter fullscreen mode Exit fullscreen mode

답장, 분류:

gws gmail +reply --message-id <ID> --body "Thanks!"
gws gmail +triage
Enter fullscreen mode Exit fullscreen mode

Calendar

이벤트 생성:

gws calendar +insert --summary "Sprint Planning" --start "2026-03-20T10:00" --end "2026-03-20T11:00" --attendees "team@example.com"
Enter fullscreen mode Exit fullscreen mode

오늘 일정 보기:

gws calendar +agenda --today
Enter fullscreen mode Exit fullscreen mode

Sheets

행 추가:

gws sheets +append --spreadsheetId <ID> --range "Sheet1!A:C" --values "Task X,Done,2026-03-16"
Enter fullscreen mode Exit fullscreen mode

Docs

텍스트 삽입:

gws docs +write --documentId <ID> --text "New section added via Google Workspace CLI"
Enter fullscreen mode Exit fullscreen mode

Chat

메시지 전송:

gws chat +send --space <SPACE_ID> --text "Deployment complete 🚀"
Enter fullscreen mode Exit fullscreen mode

모든 명령에서 --dry-run을 사용하면 실행 없이 API 호출을 미리 확인할 수 있습니다. 전체 페이지 매김이 필요하다면 --page-all 옵션을 추가하세요.

고급 구성 및 전역 옵션

환경 변수 또는 .env 파일로 설정을 유지할 수 있습니다:

export GOOGLE_WORKSPACE_CLI_DEFAULT_PARAMS='{"prettyPrint":true}'
Enter fullscreen mode Exit fullscreen mode

타임아웃, 출력 포맷(--json, --yaml), 파일 기반 키체인 등도 조정 가능. 전체 구성 확인:

gws config
Enter fullscreen mode Exit fullscreen mode

AI 에이전트 및 프롬프트와의 통합

스킬 설치 후, 에이전트가 Google Workspace CLI를 자동 호출합니다.

"use gws" 프롬프트 패턴

예시:

  • "Google Workspace CLI를 사용하여 최근 Drive 파일 목록 표시"
  • "Google Workspace CLI로 후속 이메일 전송"

자동 호출 규칙

에이전트 지침(예: CLAUDE.md, Cursor 규칙)에 다음을 추가:

"Gmail, Drive, Calendar, Sheets, Docs, Chat 관련 작업 시, 응답 전에 Google Workspace CLI 명령을 자동으로 사용하세요. 서비스와 메서드부터 결정합니다."

에이전트는 파일 경로나 JSON 결과를 반환해 컨텍스트를 간결하게 유지합니다.

Apidog와 함께 완벽한 API 신뢰 구축

Google Workspace CLI로 API 즉시 액세스가 가능하지만, 페이로드/범위/응답 디버깅에는 Apidog 클라이언트 활용이 유용합니다.

실전 워크플로우:

  • 에이전트가 Sheet에 추가 제안 → Apidog에서 Sheets.values.append 페이로드 미리 테스트
  • Gmail 전송 범위 문제 → 요청 시각적으로 빌드 및 실행
  • 서비스 계정 키/사용자 토큰을 변수로 저장 → 계정 전환 및 검증

Google Workspace CLI + Apidog 조합으로 실시간 액세스와 검증된 반복 API 테스트를 동시에 확보할 수 있습니다.

자주 묻는 질문

Q: Google Workspace CLI가 내 데이터를 외부로 전송합니까?

A: Google API로 직접 호출만 하며, 귀하의 콘텐츠는 Google 계정을 벗어나지 않습니다.

Q: 어떤 서비스를 지원합니까?

A: Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, Script 등 모든 동적 Workspace API.

Q: 명령의 최신성은?

A: 실시간 Discovery Service로 바로 최신 메서드가 반영됩니다.

Q: API 키가 필요한가요?

A: 표준 Google OAuth 또는 서비스 계정만 필요하며, 별도의 API 키 불필요.

Q: 어떤 에이전트/에디터를 지원합니까?

A: Claude Code, Cursor, OpenClaw, Gemini CLI, VS Code 확장 등 MCP 및 Agent Skills 호환 도구 모두 지원.

Q: 원시 명령과 + 도우미의 차이?

A: 원시 명령은 정확한 Discovery 메서드(예: drive.files.list), + 도우미는 자주 쓰는 작업 단축키(+upload, +send 등).

Q: AI 에이전트 없이도 사용 가능합니까?

A: 네. 스크립트, 자동화, 일상 터미널 작업에 모두 적합합니다.

추가 자료

Top comments (0)