Google Workspace CLI (gws): Drive·Gmail·Calendar를 한 CLI로 다루는 도구
Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin 등 Google Workspace API를 하나의 Rust 기반 CLI에서 다루는 도구. Google Discovery Service의 API 정의를 실행 시 읽어 명령을 동적으로 구성하며 JSON 출력, 스키마 조회, 페이지 처리, 업무별 헬퍼와 에이전트 스킬로 사람과 AI 에이전트의 자동화를 돕는다. Google 조직 저장소이나 공식 지원 Google 제품은 아니다.
주요 기능
- Discovery API 기반 동적 명령과 24시간 스키마 캐시
- 구조화 JSON/NDJSON 출력, –dry-run, –page-all, gws schema
- Gmail triage·reply, Calendar agenda, Sheets read·append, Drive upload 등의 헬퍼
- OAuth·서비스 계정·기존 토큰·CI용 자격 증명 사용
- Google Model Armor 선택 연동 및 Gemini CLI 확장
구조
Rust CLI가 서비스명을 먼저 파싱하고 Google Discovery Document를 가져와 clap 명령 트리를 구성해요. 이후 나머지 인자를 파싱해 인증된 HTTP 요청을 실행하며 결과를 JSON으로 반환해요. Discovery 문서는 24시간 캐시돼요.
누구에게 쓸모 있나요
Google Workspace의 파일·메일·일정·문서를 CLI나 코딩 에이전트로 자동화하려는 개발자.
설치 전 준비
- npm 설치 시 Node.js 18+; 사전 빌드 바이너리는 npm 불필요
- Google 계정 및 OAuth 자격 증명용 Google Cloud 프로젝트 필요
- gws auth setup 자동 구성에는 gcloud 필요. 미설치 시 수동 Desktop OAuth client 구성
- CLI는 Apache-2.0 오픈소스. 별도 CLI 이용 요금은 README에 명시되지 않으며 Google API·Workspace·Model Armor의 요금 및 할당량은 별도 확인
- OS·아키텍처에 맞는 GitHub Releases 바이너리 사용
- Homebrew 경로는 macOS·Linux
- 로컬 대화형 OAuth 또는 CI·서버용 자격 증명 방식
설치 방법
설치 방법 1
권장: GitHub Releases에서 OS·아키텍처용 사전 빌드 바이너리를 받아 PATH에 배치 이번 조사에서는 다운로드·설치하지 않았어요.
설치 방법 2
공식 README에 문서화된 경로예요. 이번 조사에서는 설치·실행하지 않았어요.
npm install -g @googleworkspace/cli설치 방법 3
공식 README에 문서화된 경로예요. 이번 조사에서는 설치·실행하지 않았어요.
cargo install --git https://github.com/googleworkspace/cli --locked설치 방법 4
공식 README에 문서화된 경로예요. 이번 조사에서는 설치·실행하지 않았어요.
nix run github:googleworkspace/cli설치 방법 5
공식 README에 문서화된 경로예요. 이번 조사에서는 설치·실행하지 않았어요.
brew install googleworkspace-cli사용 방법
- gws auth setup
- gws auth login -s drive,gmail,sheets
- gws drive files list –params ‘{“pageSize”: 5}’
- gws schema drive.files.list
- gws calendar +agenda
- npx skills add https://github.com/googleworkspace/cli
비용과 API 키
CLI는 Apache-2.0 공개 도구이며 README에 별도 이용료는 명시되지 않습니다. Google Workspace/API·Model Armor의 계정 요금과 사용량·할당량은 별도 확인해야 해요.
라이선스
Apache-2.0 — 고정 커밋의 라이선스 원문 확인. 배포 시 해당 고지·조건을 준수해야 해요.
주의사항과 알려진 이슈
- 활발한 개발 중이며 v1.0 이전 호환성 파괴 변경 가능
- 공식 지원 Google 제품이 아님
- 미검증 OAuth 앱은 약 25개 scope 제한; recommended 프리셋은 85개 이상으로 실패할 수 있으므로 필요한 서비스만 선택
- 자격 증명은 AES-256-GCM으로 암호화되지만 파일 keyring·평문 export·토큰·서비스 계정 키 취급에 주의. 비밀을 저장소에 커밋하지 말 것
- 에이전트가 실제 메일 발송·파일 수정 등을 할 수 있으므로 최소 권한 및 –dry-run을 사용. Model Armor 기본 warn은 차단 보장이 아님
- README 상단 40+ skills와 본문 100+ skills 표기가 혼재하여 정확한 개수 대신 다수의 스킬로 기술
확인 범위
확인 날짜: 2026-11-05
확인 커밋: cd3697e07eb520056dcf142d0c7439bbb9ba32e9
확인한 범위: 공식 GitHub 저장소 메타데이터·main 브랜치 HEAD·README·라이선스를 정적으로 확인했어요. 비아카이브 상태이며 요청 저장소 이름이 canonical 경로와 일치해요.
확인 한계: 대상 프로그램 설치·실행·계정 연결·토큰 생성·유료 호출은 하지 않았어요. 성능·플랫폼별 실제 동작·전체 보안 감사·배포 채널 최신 버전은 미검증이에요.