개발자라면 하루에도 몇 번씩 브라우저 탭을 왔다 갔다 한다. 코드를 짜다가 Gmail을 열고, Slack을 확인하고, Google Calendar에서 다음 회의 시간을 보고, 다시 터미널로 돌아온다. 이 왔다 갔다에 평균 23분이 든다는 연구 결과가 있다 (UC Irvine, Gloria Mark). Google Workspace CLI는 Gmail 발송, Drive 파일 업로드, Calendar 일정 조회, Sheets 데이터 쓰기를 전부 터미널 명령어 한 줄로 처리할 수 있게 만든 도구다. 2026년 3월 Google이 공개한 이 Rust 기반 CLI 도구는 출시 한 달 만에 GitHub 스타 23,800개를 넘겼다. 이번 포스팅에서는 Google Workspace CLI 설치부터 실전 워크플로우 자동화까지 정리하고자 한다.
브라우저 없이 Google 서비스를 다루는 Google Workspace CLI
Google Workspace CLI(이하 gws)는 Gmail, Drive, Calendar, Sheets, Docs, Chat 등 85개 이상의 Google API를 터미널에서 직접 호출할 수 있는 CLI 도구다. Rust로 작성되었고, 눈에 띄는 점이 하나 있다. 명령어 체계를 런타임에 Google Discovery Service에서 동적으로 빌드한다. Google이 새 API를 추가하면 gws도 별도 업데이트 없이 그 명령어를 바로 사용할 수 있다.
2026년 4월 기준 최신 버전은 v0.22.5이며, MIT 라이선스로 공개되어 있다. 다만 공식 Google 지원 제품은 아니고 개발자 샘플(developer sample) 성격이므로, 프로덕션 환경에서는 이 점을 고려해야 한다. 저장소 URL은 github.com/googleworkspace/cli다.
Google Workspace CLI 설치는 한 줄이면 충분하다
gws는 macOS, Linux, Windows에서 모두 동작하며, 설치 방법은 4가지가 있다.
macOS (Homebrew)
brew install googleworkspace-cliHomebrew가 설치된 macOS 환경에서 가장 간단한 방법이다. 설치 후 gws 명령어가 PATH에 자동 등록된다.
npm (Node.js 환경)
npm install -g @googleworkspace/cliNode.js 18 이상이 설치된 환경에서 사용할 수 있다. 설치 시 postinstall 스크립트가 OS에 맞는 Rust 바이너리를 자동 다운로드하고, SHA256 체크섬으로 무결성을 검증한다.
Cargo (Rust 환경)
cargo install --git https://github.com/googleworkspace/cli --lockedRust 툴체인이 설치된 환경에서 소스 코드를 직접 컴파일하여 설치하는 방식이다. 최신 커밋을 바로 반영할 수 있다는 장점이 있지만, 컴파일 시간이 수 분 소요된다.
바이너리 직접 다운로드
# GitHub Releases 페이지에서 OS/아키텍처에 맞는 바이너리 다운로드
curl -LO https://github.com/googleworkspace/cli/releases/download/v0.22.5/gws-aarch64-apple-darwin.tar.gz
tar xf gws-aarch64-apple-darwin.tar.gz
sudo mv gws /usr/local/bin/위 명령어는 Apple Silicon Mac용 바이너리를 다운로드하는 예시다. Intel Mac이라면 x86_64-apple-darwin, Linux라면 x86_64-unknown-linux-gnu로 바꾸면 된다. CI/CD 환경이나 Docker 이미지에서 특정 버전을 고정할 때 유용하다.
OAuth 인증 설정, 처음 한 번만 하면 된다
Google Workspace CLI를 사용하려면 Google Cloud 프로젝트와 OAuth 인증이 필요하다. gws auth setup 명령어가 이 과정을 자동으로 처리한다.
# 1단계: Google Cloud 프로젝트 생성 및 OAuth 설정 (최초 1회)
gws auth setup
# 2단계: OAuth 로그인 (스코프 선택 포함)
gws auth logingws auth setup을 실행하면 Google Cloud 프로젝트 생성, API 활성화, OAuth 동의 화면 구성을 대화형으로 안내한다. 내부적으로 gcloud CLI를 활용하므로 사전에 Google Cloud SDK가 설치되어 있어야 한다. 설정이 완료되면 “Setup complete! Run gws auth login to authenticate.” 메시지가 출력된다.
gws auth login을 실행하면 사용할 Google 서비스의 OAuth 스코프를 선택하는 화면이 나온다. 모든 서비스를 한꺼번에 선택할 수도 있고, 필요한 서비스만 골라서 인증할 수도 있다.
# 특정 서비스만 스코프 지정하여 로그인
gws auth login -s drive,gmail,sheets위 명령어처럼 -s 플래그로 필요한 서비스만 지정하면 최소 권한 원칙을 지킬 수 있다. 비인증(unverified) OAuth 앱은 스코프가 약 25개로 제한되므로, 필요한 서비스만 선택하는 것이 실용적이다.
인증 토큰은 AES-256-GCM으로 암호화되어 로컬에 저장되며, OS 키링에 암호화 키를 보관한다. 토큰 갱신도 자동으로 처리되므로 한 번 인증하면 이후에는 별도 작업 없이 바로 명령어를 사용할 수 있다.
# CI/CD 환경용: 인증 정보 내보내기
gws auth export --unmasked > credentials.json
# 헤드리스 서버에서 사용
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
gws drive files list위 방법은 브라우저가 없는 CI/CD 서버나 원격 머신에서 Google Workspace CLI를 사용할 때 필요하다. 데스크톱에서 인증한 뒤 gws auth export로 크리덴셜을 내보내고, 환경 변수로 지정하면 된다.
Google Workspace CLI 서비스별 핵심 명령어
Google Workspace CLI의 명령어 체계는 gws {서비스} {리소스} {메서드} 형태를 따른다. 여기에 + 접두사가 붙은 헬퍼 명령어가 있는데, 복잡한 API 파라미터를 간단하게 추상화한 단축 명령이다.
Gmail: 터미널에서 메일 보내고 분류하기
# 이메일 발송
gws gmail +send --to alice@example.com --subject "배포 완료 알림" --body "v2.1.0 배포가 완료되었습니다."
# 읽지 않은 메일 요약
gws gmail +triage
# 특정 메일에 답장
gws gmail +reply --message-id MESSAGE_ID --body "확인했습니다. 감사합니다."
# 새 메일 실시간 스트리밍 (NDJSON 형식)
gws gmail +watch+send는 수신자, 제목, 본문만 지정하면 되는 단축 명령이다. Gmail API의 users.messages.send를 직접 호출하는 것보다 훨씬 간결하다. +triage는 읽지 않은 이메일을 요약해서 보여주므로 아침에 터미널을 열자마자 받은편지함 상태를 빠르게 파악할 수 있다. +watch는 새 메일이 도착할 때마다 NDJSON 형식으로 출력하므로, 파이프라인으로 연결하여 Slack 웹훅이나 알림 시스템과 조합할 수 있다.
Google Drive: 파일 관리를 명령어 한 줄로
# 최근 파일 5개 조회
gws drive files list --params '{"pageSize": 5}'
# 파일 업로드
gws drive +upload ./report.pdf --name "Q1 리포트"
# 특정 폴더에 업로드
gws drive +upload ./data.csv --parent FOLDER_ID
# 전체 파일 목록 자동 페이지네이션
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'--page-all 플래그는 결과가 여러 페이지에 걸쳐 있을 때 자동으로 모든 페이지를 순회하며 NDJSON으로 출력한다. --page-limit 5로 최대 페이지 수를 제한하거나, --page-delay 200으로 API 요청 간 딜레이(ms)를 설정할 수도 있다. jq와 조합하면 파일 이름만 추출하는 등 원하는 필드를 자유롭게 가공할 수 있다.
Google Calendar: 일정 조회와 생성
# 오늘 일정 조회
gws calendar +agenda --today
# 특정 타임존 기준 일정 조회
gws calendar +agenda --today --timezone Asia/Seoul
# 새 일정 생성
gws calendar +insert --summary "코드 리뷰" --start "2026-04-07T14:00:00+09:00" --end "2026-04-07T15:00:00+09:00"+agenda는 당일 또는 향후 일정을 깔끔하게 정리해서 보여준다. 타임존을 별도로 지정하지 않으면 Google 계정에 설정된 타임존을 사용하며, 24시간 캐시된다. +insert로 회의를 빠르게 잡을 수 있어서, Slack에서 “내일 3시에 리뷰 회의 잡아줘”라는 요청을 받았을 때 브라우저를 열 필요 없이 터미널에서 바로 처리 가능하다.
Google Sheets: 데이터 읽기/쓰기
# 특정 범위 데이터 읽기
gws sheets +read --spreadsheet SPREADSHEET_ID --range 'Sheet1!A1:C10'
# 데이터 추가 (append)
gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95,A+"
# 새 스프레드시트 생성
gws sheets spreadsheets create --json '{"properties": {"title": "서버 모니터링 로그"}}'+read와 +append는 Sheets API의 복잡한 요청 본문을 간소화한 헬퍼 명령이다. 셸 스크립트에서 서버 모니터링 데이터를 정기적으로 Sheets에 기록하거나, 배포 이력을 자동으로 추가하는 용도로 활용할 수 있다. 주의할 점은 bash에서 !가 히스토리 확장 문자로 해석되므로 범위 지정 시 반드시 작은따옴표(')로 감싸야 한다.
매일 반복하는 작업, 셸 스크립트 하나로 끝내기
개별 명령어를 하나씩 쓰는 것도 괜찮지만, 여러 서비스를 엮어서 워크플로우로 만들면 효과가 확 달라진다. gws에는 자주 쓰는 조합을 미리 묶어둔 워크플로우 명령이 있다.
# 데일리 스탠드업 리포트: 오늘 회의 + 열린 할 일 정리
gws workflow +standup-report
# 다음 회의 준비: 안건 및 참석자 조회
gws workflow +meeting-prep
# 이메일을 Google Tasks로 변환
gws workflow +email-to-task
# 주간 업무 요약 생성
gws workflow +weekly-digest+standup-report는 Calendar에서 오늘 예정된 미팅을 가져오고, Tasks에서 열린 할 일 목록을 조합하여 스탠드업에 필요한 정보를 한 번에 출력한다. 매일 아침 터미널을 열고 이 명령어 하나만 실행하면 오늘 뭘 해야 하는지 바로 파악할 수 있다.
셸 스크립트로 커스텀 워크플로우를 만드는 것도 간단하다.
#!/bin/bash
set -euo pipefail
# deploy-notify.sh — 배포 후 팀에 자동 알림
VERSION=$1
TIMESTAMP=$(date '+%Y-%m-%d %H:%M')
# 1. 배포 이력을 Sheets에 기록
gws sheets +append \
--spreadsheet SPREADSHEET_ID \
--values "${VERSION},${TIMESTAMP},success"
# 2. 팀 Chat 채널에 알림
gws chat spaces messages create \
--params '{"parent": "spaces/SPACE_ID"}' \
--json "{\"text\": \"v${VERSION} 배포 완료 (${TIMESTAMP})\"}"
# 3. 담당자에게 이메일 발송
gws gmail +send \
--to team-lead@company.com \
--subject "v${VERSION} 배포 완료" \
--body "배포가 정상적으로 완료되었습니다. 배포 시각: ${TIMESTAMP}"위 스크립트는 배포가 완료된 후 실행하면 Sheets에 이력 기록, Chat 채널 알림, 이메일 발송을 한 번에 처리한다. CI/CD 파이프라인의 post-deploy 단계에 넣으면 배포 알림을 완전히 자동화할 수 있다. --dry-run 플래그를 추가하면 실제 API 호출 없이 요청 내용을 미리 확인할 수 있으므로, 스크립트 디버깅 시 유용하다.
AI 에이전트에 Google 서비스 손잡이를 달아주기
gws에는 CLI 자체 말고도 한 가지 재미있는 쓸모가 있다. MCP(Model Context Protocol) 서버로 띄워서 AI 에이전트가 Google 서비스를 직접 조작하게 만들 수 있다. 사전 구성된 AI Agent Skill도 100개 이상 들어 있다.
# MCP 서버 활성화
gws mcp이렇게 띄우면 Claude Code나 Gemini CLI 같은 MCP 클라이언트에서 gws에 연결할 수 있다. 연결된 AI 에이전트는 Gmail 발송, Drive 파일 관리, Calendar 일정 생성을 직접 실행한다.
Gemini CLI라면 확장 설치 방식도 있다.
# Gemini CLI 확장으로 설치
gws auth setup
gemini extensions install https://github.com/googleworkspace/cligws 인증은 gws 자체가 관리하기 때문에, 터미널에서 한 번 로그인해두면 Gemini CLI 확장이 그 크리덴셜을 그대로 가져다 쓴다.
Google Workspace CLI의 Skills은 OpenFramework를 통해 설치할 수 있다.
# 전체 Skills 설치
npx skills add https://github.com/googleworkspace/cli
# 특정 서비스 Skills만 설치
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmailSkill이 하는 일은 결국 복잡한 Google API 파라미터를 AI 에이전트가 이해하기 쉬운 형태로 감싸주는 것이다. 예를 들어 “지난주 안 읽은 메일을 요약해서 Google Doc으로 만들어줘”라고 말하면, 에이전트가 gws 명령어 여러 개를 조합해서 처리하는 식이다.
Google Workspace CLI 사용 팁과 주의사항
JSON 출력과 jq 조합: gws의 모든 응답은 JSON 형식이므로 jq와 조합하면 원하는 데이터만 정확히 추출할 수 있다.
# Drive에서 PDF 파일만 찾기
gws drive files list --params '{"q": "mimeType=\"application/pdf\"", "pageSize": 10}' | \
jq -r '.files[] | "\(.name) — \(.id)"'위 명령어는 Drive에서 PDF 파일만 검색하여 파일 이름과 ID를 한 줄씩 출력한다. --params에 Google Drive API의 검색 쿼리를 그대로 전달할 수 있어, API 문서를 참고하면 세밀한 검색이 가능하다.
API 스키마 확인: 특정 API의 요청/응답 구조를 터미널에서 바로 확인할 수 있다.
# Drive files.list API 스키마 조회
gws schema drive.files.list이 명령어는 drive.files.list API가 어떤 파라미터를 받고 어떤 응답을 반환하는지 구조를 보여준다. Google API 문서를 브라우저로 찾아가지 않아도 되므로 개발 중에 빠르게 참고할 수 있다.
주의사항:
- v1.0 이전이므로 하위 호환성이 보장되지 않는다. 버전 업데이트 시 명령어 변경이 있을 수 있다
- Google 공식 지원 제품이 아니므로, 프로덕션 환경에서는 충분한 테스트 후 사용해야 한다
- 비인증 OAuth 앱은 테스트 모드에서 스코프가 약 25개로 제한된다
더 알아보기
- Google Workspace CLI 공식 GitHub — 전체 명령어 레퍼런스와 Skills 목록
- Google Workspace CLI 릴리스 노트 — 최신 버전 변경사항
- gws 명령어 레퍼런스 — 서비스별 상세 명령어 문서
Google Workspace CLI 보안, 이것만은 챙기자
gws는 Google 서비스에 대한 읽기/쓰기 권한을 터미널에 열어주는 도구다. 편리한 만큼 보안도 신경 써야 한다. 개인 개발 환경에서 실제로 주의할 포인트 세 가지를 짚는다.
MCP 모드는 읽기 전용으로 시작하자. gws mcp로 AI 에이전트에 Google 서비스 접근을 열어주면, 에이전트가 사용자의 OAuth 토큰으로 Gmail 발송이나 Drive 파일 삭제를 직접 실행한다. 문제는 이 행위가 전부 사용자 본인의 작업으로 기록된다는 점이다. Prompt Injection 등으로 에이전트가 의도하지 않은 동작을 할 수 있으므로, 처음에는 읽기 전용 스코프(gws auth login -s drive.readonly,gmail.readonly)로 제한하고 필요할 때만 쓰기 권한을 추가하는 방식이 안전하다.
크리덴셜 파일은 반드시 관리하자. gws는 인증 토큰을 AES-256-GCM으로 암호화해서 OS 키링에 보관한다. 여기까지는 괜찮다. 문제는 CI/CD용으로 gws auth export --unmasked를 실행하면 크리덴셜이 평문 JSON 파일로 떨어진다는 것이다. 이 파일이 git에 커밋되거나 빌드 캐시에 남으면 토큰이 유출된다. .gitignore에 credentials.json을 반드시 추가하고, CI 파이프라인에서는 작업 완료 후 파일 삭제를 보장해야 한다.
# CI 파이프라인에서 크리덴셜 정리 보장
trap 'rm -f credentials.json' EXIT
gws auth export --unmasked > credentials.json
# ... gws 명령어 실행 ...위 스크립트에서 trap 명령은 스크립트가 정상 종료하든 실패하든 credentials.json 파일을 삭제하도록 보장한다. CI 환경에서 크리덴셜 파일이 잔존하는 사고를 방지하는 기본적인 안전장치다.
프로덕션 환경에서는 공식 도구를 쓰자. gws는 아직 v1.0 이전이고, Google 공식 지원 제품이 아니다. 보안 취약점이 발견되어도 Google 보안팀의 체계적인 대응(SLA)을 기대하기 어렵다. 규제 준수(SOC 2, GDPR 등)가 필요한 환경이라면 공식 Google Cloud CLI(gcloud)나 각 언어별 API 클라이언트 라이브러리를 사용하는 것이 맞다. gws는 개인 개발 환경이나 내부 자동화 스크립트 용도에 적합하다.
마치며
솔직히 v1.0도 안 나온 도구를 프로덕션에 넣으라고 권하기는 어렵다. 공식 Google 지원 제품도 아니다. 그런데 개인 워크플로우 자동화 용도로는 이미 꽤 쓸 만하다. 배포 끝나고 Sheets에 기록 남기고 Chat에 알림 보내는 스크립트를 한 번 짜놓으면, 브라우저를 왔다 갔다 하던 시간이 사라진다. 터미널을 안 떠나도 되는 건 편의 이상이다. 코딩 중에 Gmail 탭으로 전환하는 순간 머릿속 컨텍스트가 날아가는 경험, 다들 해봤을 것이다. 그 3초를 없애는 도구라고 생각하면 설치해볼 이유는 충분하다.