TL;DR

gws는 Google Workspace의 모든 공개 API를 단일 CLI 인터페이스로 제공하기 위해 설계된 도구로, Google Discovery Service를 런타임에 조회해 명령 트리를 자동 생성한다. 출력은 성공·오류·다운로드 메타데이터를 포함한 구조화된 JSON이고, 페이징을 NDJSON으로 스트리밍하는 등 파이프라인 처리를 고려한 기능을 제공한다. 인증은 대화형(OAuth), 헤드리스(CI용 export flow), 서비스 계정 등 여러 모드를 지원하고, Model Armor 템플릿으로 응답을 사전 검사할 수 있어 에이전트 통합 시 안전성 제어가 가능하다. 레포는 다수의 Agent Skills를 포함하며 Gemini CLI 확장으로 에이전트가 직접 gws 명령을 호출하게 할 수 있다. 사전 빌드 바이너리·npm·Homebrew·cargo·Nix 등의 설치 경로를 제공해 빠르게 도입할 수 있지만, 공식 Google 제품은 아니며 현재 활발히 개발 중이라 v1.0 전에는 파괴적 변경이 발생할 수 있고, OAuth 앱이 검증되지 않은 경우 scope 제한(약 25개)으로 로그인 실패 가능성이 있다.

주요 기능

• Google Discovery Service에서 런타임으로 명령 트리를 생성
• 모든 출력과 에러를 구조화된 JSON으로 반환해 에이전트 연동에 최적화
• 여러 인증 흐름(interactive, headless, service-account, pre-obtained token)을 지원
• 100개 이상의 Agent Skills 및 '+' 접두사로 제공되는 헬퍼 커맨드를 제공
• 자동 페이징(NDJSON), multipart 업로드, 스키마 인트로스펙션(s gws schema ...) 지원

어떻게 동작하는가

gws는 argv[1]로 서비스 이름을 판별한 뒤 해당 서비스의 Discovery Document를(캐시 24시간) 가져와 clap::Command 트리를 동적으로 생성하고 나머지 인수를 재파싱한다. 이후 인증을 수행하고 HTTP 요청을 구성해 실행하며 모든 출력은 구조화된 JSON으로 반환된다.

해결 문제

Google Workspace의 방대한 REST API 문서에 대해 curl 중심의 수동 호출을 줄이고, 런타임에 자동 생성되는 일관된 CLI 표면과 구조화된 JSON 출력을 통해 스크립트·CI·AI 에이전트 통합을 단순화한다.

지금 주목받는 이유

Gemini CLI 확장과 다수의 Agent Skills를 통해 LLM 기반 에이전트와의 통합 사례가 즉시 가능해지므로 에이전트-작업 도구 연동 수요와 맞물려 주목받고 있다.

차별점

• Google Discovery Service를 런타임에 읽어 clap 명령 트리를 자동 생성하므로 API 변경을 수동으로 유지관리할 필요가 없다
• 응답을 표준화된 JSON으로 출력해 LLM 에이전트와의 연동(스킬 + Gemini 확장)이 용이하다
• Model Armor 통합으로 API 응답에 대한 프롬프트 인젝션 검사(템플릿 기반)를 바로 적용할 수 있다
• 다중 설치 경로(바이너리, npm, Homebrew, cargo, Nix)를 제공해 배포·자동화 환경에 유연하게 적응한다

사용 사례

• 로컬 스크립트나 CI 파이프라인에서 서비스 계정·헤드리스 환경으로 Drive/Gmail/Sheets 등 API 호출을 자동화하고 결과를 NDJSON으로 파이프라인 처리
• LLM 에이전트(예: Gemini CLI 확장)에게 구조화된 입력·출력을 제공해 이메일 전송·문서 조작·일정 준비 같은 워크플로를 대행시키기
• 관리자 작업 자동화—GCP OAuth 설정·API 활성화·계정 기반 권한 검사 후 헬퍼 커맨드를 통해 반복 작업 단순화
• 보안이 필요한 응답을 Model Armor 템플릿으로 사전 검사해 에이전트가 민감한 데이터를 잘못 처리하는 것을 방지

시작하기

릴리스 페이지에서 OS·아키텍처에 맞는 사전 빌드 바이너리를 다운로드해 PATH에 놓거나 npm으로 설치(npm install -g @googleworkspace/cli), 또는 소스에서 빌드(cargo install --git https://github.com/googleworkspace/cli --locked). 초기 설정은 gws auth setup으로 Cloud 프로젝트·API 활성화·로그인을 진행한 뒤 gws drive files list --params '{"pageSize": 5}' 같은 명령으로 동작을 확인한다.

요구사항

• Node.js 18+ (npm 설치를 위한 경우)
• Google Cloud 프로젝트(오Auth 클라이언트 생성·API 활성화를 위해)
• Google 계정(Workspace 접근 권한)
• Rust/cargo (소스에서 빌드하려는 경우 선택적)
• gcloud CLI (gws auth setup 자동화 사용 시 필요)