Google Workspace는 기업과 개발자들이 가장 많이 사용하는 협업 플랫폼 중 하나입니다. 하지만 Drive, Gmail, Calendar, Docs, Sheets, Chat, Admin 등 다양한 서비스를 자동화하거나 통합 관리하려면 여러 API와 도구를 따로 사용해야 하는 번거로움이 있습니다.
이러한 문제를 해결하기 위해 등장한 도구가 gws(Google Workspace CLI) 입니다. gws는 Google Workspace의 다양한 API를 단일 명령줄 인터페이스(CLI) 로 제어할 수 있도록 설계된 도구로, 자동화 스크립트, AI 에이전트 연동, CI 환경까지 폭넓게 활용할 수 있습니다.
특히 Google Discovery Service 기반의 동적 명령 생성, 구조화된 JSON 출력, AI 에이전트 스킬 지원, MCP 서버 기능 등을 통해 사람뿐 아니라 AI 중심 자동화 환경에서도 활용 가능한 CLI라는 점이 특징입니다.
이번 글에서는 gws의 개념, 주요 기능, 인증 방식, AI 에이전트 통합 구조, 아키텍처, 활용 방법까지 정리해보겠습니다.
gws란 무엇인가
gws(Google Workspace CLI) 는 Google Workspace API를 하나의 CLI에서 실행할 수 있도록 만든 통합 도구입니다.
기존에는 Google Workspace 서비스를 자동화하려면 서비스별 API를 따로 호출하거나 SDK를 사용해야 했습니다. 하지만 gws는 이러한 과정을 단순화하여 Drive, Gmail, Calendar, Docs, Sheets, Chat, Admin 등 모든 Workspace API를 CLI에서 직접 실행할 수 있도록 제공합니다.
주요 특징은 다음과 같습니다.
- 하나의 CLI에서 Google Workspace API 전체 실행 가능
- Google Discovery Service 기반 명령 자동 생성
- AI 에이전트 연동을 위한 JSON 출력 지원
- 다양한 인증 방식 제공
- 자동화 및 DevOps 환경에 적합한 구조
즉, Google Workspace 운영과 자동화를 위한 통합 CLI 플랫폼이라고 볼 수 있습니다.
gws의 주요 기능
1. Google Workspace API 통합 실행
gws는 Google Workspace의 주요 서비스를 단일 CLI로 제어할 수 있습니다.
지원 서비스 예시
- Drive
- Gmail
- Calendar
- Docs
- Sheets
- Chat
- Admin
이러한 API들을 각각 별도의 SDK나 API 호출 없이 명령어 기반으로 실행할 수 있습니다.
또한 CLI 사용성을 위해 다음 기능이 제공됩니다.
- 탭 자동완성
- --help 명령
- --dry-run
- 자동 페이지네이션
즉, 개발자 친화적인 CLI 환경을 제공합니다.
2. Google Discovery Service 기반 동적 명령 생성
gws의 핵심 특징 중 하나는 동적 명령 생성 구조입니다.
Google Workspace API는 계속 업데이트되는데, gws는 이를 Google Discovery Service를 통해 자동 반영합니다.
동작 방식
- 서비스 식별
- Discovery 문서 다운로드 (24시간 캐시)
- CLI 명령 구조 생성
- 인자 재파싱
- 인증 수행
- HTTP 요청 실행
즉,
새로운 API가 추가되면
→ CLI 업데이트 없이
→ 자동으로 명령이 생성됩니다.
이는 CLI 유지보수 부담을 크게 줄이는 구조입니다.
JSON 기반 출력 구조
gws의 모든 결과는 구조화된 JSON 형식으로 출력됩니다.
출력 데이터에는 다음 정보가 포함됩니다.
- API 응답 데이터
- 오류 정보
- 메타데이터
이 구조 덕분에 다음과 같은 활용이 가능합니다.
- 자동화 스크립트
- AI 에이전트
- 파이프라인 처리
- DevOps 시스템 연동
특히 LLM 기반 자동화 환경에서 활용하기 쉬운 구조라는 점이 장점입니다.
AI Agent 통합 기능
gws는 단순 CLI를 넘어 AI 에이전트와의 통합을 고려한 설계를 가지고 있습니다.
100개 이상의 AI 스킬 제공
저장소에는 100개 이상의 AI 스킬(SKILL.md) 이 포함되어 있습니다.
이 스킬들은 다음 작업을 자동화할 수 있습니다.
- Gmail 관리
- Drive 파일 작업
- Calendar 일정 관리
- Workspace 워크플로우 실행
스킬 설치 예시
npx skills add
또는 특정 스킬만 선택 설치할 수 있습니다.
Gemini CLI 확장 지원
gws는 Gemini CLI와 연동할 수 있습니다.
설치 명령
gemini extensions install https://github.com/googleworkspace/cli
설치 후에는
- Gemini 에이전트가 gws 명령 실행
- gws 스킬 직접 호출
- 인증 정보 자동 상속
즉, 별도 로그인 없이 AI가 Workspace 작업을 자동 실행할 수 있습니다.
MCP 서버 기능
gws는 MCP(Model Context Protocol) 서버 모드도 제공합니다.
MCP 서버 실행 예시
gws mcp -s drive,gmail,calendar
이 명령은 Workspace API를 MCP 도구 형태로 노출합니다.
연동 가능한 클라이언트 예시
- Claude Desktop
- Gemini CLI
- VS Code
각 서비스는 약 10~80개의 도구를 제공하며, 클라이언트의 도구 제한(약 50~100개)에 맞게 선택할 수 있습니다.
추가 옵션
- --workflows
- --helpers
이를 통해 워크플로우 및 헬퍼 도구도 함께 노출할 수 있습니다.
인증 방식
gws는 다양한 환경에서 사용할 수 있도록 여러 인증 방식을 지원합니다.
1. 로컬 인터랙티브 인증
- OAuth 기반 인증
- 자격 증명 AES-256-GCM 암호화
- OS 키링에 저장
2. 수동 OAuth 설정
Google Cloud Console에서 클라이언트를 직접 생성하여 인증할 수 있습니다.
3. 브라우저 / 에이전트 인증
- 수동 승인
- 자동 승인
AI 에이전트 환경에서도 사용할 수 있습니다.
4. CI / 서버 환경 인증
CI 환경에서는 다음 방식이 사용됩니다.
gws auth export
자격 증명을 환경 변수로 설정하여 서버 환경에서도 사용할 수 있습니다.
5. Service Account 및 토큰
다음 인증도 지원합니다.
- Service Account
- 사전 발급 토큰
인증 우선순위
- 토큰
- 자격 파일
- 키링 저장 정보
보안 기능
gws는 Model Armor 기능을 통해 응답 보안을 강화합니다.
이 기능은 API 응답을 검사하여 프롬프트 인젝션 공격을 차단합니다.
환경 변수 설정
GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE
GOOGLE_WORKSPACE_CLI_SANITIZE_MODE
이를 통해 응답 데이터 필터링을 제어할 수 있습니다.
고급 기능
gws는 CLI 자동화를 위한 여러 고급 기능도 제공합니다.
Multipart 업로드
파일 업로드와 메타데이터 생성을 동시에 수행할 수 있습니다.
페이지네이션 제어
다음 옵션을 통해 페이지 데이터를 제어합니다.
- --page-all
- --page-limit
- --page-delay
대량 데이터 처리 시 유용합니다.
문제 해결 방법
Workspace API가 활성화되지 않은 경우 다음 오류가 발생할 수 있습니다.
accessNotConfigured
해결 방법
- 오류 메시지의 enable_url 링크 클릭
- 해당 API 활성화
- 명령 재실행
또는 다음 명령으로 자동 활성화할 수 있습니다.
gws auth setup
아키텍처 구조
gws는 2단계 파싱 구조로 동작합니다.
전체 흐름
- 첫 번째 인자로 서비스 식별
- Discovery 문서 로드
- CLI 명령 트리 생성
- 인자 재파싱
- 인증 처리
- HTTP 요청 실행
- JSON 결과 출력
특히 CLI 구현에는 Rust(약 99.5%) 가 사용되었습니다.
개발 및 라이선스
- 라이선스: Apache 2.0
- 주요 언어: Rust
- 상태: 활발히 개발 중
- v1.0 이전이라 주요 변경 가능
또한 공식 Google 제품이 아닌 비공식 오픈소스 프로젝트입니다.
gws는 Google Workspace API를 단일 CLI에서 제어할 수 있도록 만든 자동화 중심 도구입니다.
핵심 특징을 정리하면 다음과 같습니다.
- Google Workspace API 통합 CLI
- Discovery 기반 동적 명령 생성
- JSON 출력 기반 자동화 친화 구조
- 100개 이상의 AI Agent 스킬 제공
- Gemini CLI 및 MCP 서버 지원
- 다양한 인증 방식 제공
- Model Armor 기반 보안 기능
특히 AI 에이전트와의 통합을 고려한 CLI라는 점에서 기존 CLI 도구들과 차별화됩니다.
앞으로 LLM 기반 자동화와 DevOps 환경이 확대될수록,
gws와 같은 AI 친화형 CLI 도구의 활용도는 더욱 높아질 것으로 기대됩니다.
https://github.com/googleworkspace/cli
GitHub - googleworkspace/cli: Google Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Adm
Google Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills. - googlework...
github.com
'잡학다식 > IT 컬럼' 카테고리의 다른 글
| Bun v1.3.10 업데이트 정리: 성능·개발자 경험·호환성까지 크게 개선된 최신 릴리스 (0) | 2026.03.05 |
|---|---|
| Electrobun: Bun과 Zig로 구현한 초고속·초경량 크로스플랫폼 데스크톱 앱 프레임워크 (0) | 2026.02.24 |
| 투명 디스플레이를 위한 설계 전략: Jetpack Compose Glimmer로 보는 AI 글래스 UI 디자인의 핵심 (0) | 2026.02.19 |
| Web 4.0: 인간 없이 스스로 벌고 진화하는 자율 AI 인터넷의 시작 (0) | 2026.02.18 |
| OpenVSCode Server 개념부터 배포, 보안 설정까지 한눈에 정리 (0) | 2026.02.14 |
