Google Workspace CLI 실전 가이드: Gmail, Drive, Calendar를 터미널에서 — AI 에이전트의 생산성 도구

브라우저를 닫고, 터미널을 열어라

1인 개발자의 하루를 솔직하게 들여다보면 이런 장면들이 반복된다. 오전에 Gmail 탭을 열어 고객 문의 이메일을 확인하고, Drive에서 어제 작업한 파일을 찾아 다운로드하고, Calendar에서 오늘 미팅 일정을 확인한다. 이 과정에서 브라우저 탭은 10개가 되고, 컨텍스트 스위칭이 일어나고, 집중력이 흩어진다.

터미널 중심으로 일하는 개발자라면 이 불편함을 더 크게 느낀다. VSCode에서 코드를 짜다가, 슬랙에서 메시지를 확인하다가, 브라우저에서 Gmail을 열고, 다시 터미널로 돌아오는 흐름이 반복된다. 이 흐름의 단절은 생산성의 적이다.

Google Workspace CLI는 이 문제를 해결하기 위해 나왔다. Gmail, Drive, Calendar, Sheets, Docs — 구글 서비스 전체를 터미널 명령어 하나로 제어하는 Rust 기반 오픈소스 도구다. 2026년 3월 공식 출시 이후 개발자 커뮤니티에서 빠르게 퍼지며 출시 수 주 만에 20.7K+ GitHub 스타를 기록했다.

이 가이드에서는 Google Workspace CLI를 설치하고, 실제 1인 개발자 워크플로우에 통합하고, AI 에이전트와 연동하는 방법을 단계별로 정리한다.

---

Google Workspace CLI란?

github.com/googleworkspace/cli는 Google이 공식으로 관리하는 오픈소스 CLI다. 핵심 기술은 Google Discovery Service를 활용한 동적 API 빌드다. Google이 제공하는 수백 개의 API 스펙을 런타임에 읽어와 단일 CLI 바이너리로 통합한다. 덕분에 Google이 새 API를 출시하면 CLI를 재빌드하지 않아도 자동으로 사용할 수 있다.

Rust로 작성된 이유가 있다. 바이너리 크기가 작고, 실행 속도가 빠르며, 메모리 안전성이 보장된다. 터미널에서 반복적으로 호출되는 도구일수록 이 특성이 중요하다.

특히 눈에 띄는 건 AGENTS.md 파일 내장이다. Claude Code, Cursor, GitHub Copilot 같은 AI 코딩 에이전트가 프로젝트의 AGENTS.md 파일을 읽어 도구 사용법을 학습한다. Google Workspace CLI는 이 파일을 기본 내장해 에이전트가 100개 이상의 skill을 자동으로 학습하도록 설계했다. AI 에이전트와의 통합을 처음부터 핵심 기능으로 기획한 도구다.

---

설치 및 초기 설정

설치

Rust 생태계의 패키지 관리자인 cargo로 설치한다.

# Rust가 없다면 먼저 설치
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Google Workspace CLI 설치
cargo install gws

# 설치 확인
gws --version

바이너리 직접 다운로드를 선호한다면 GitHub Releases 페이지에서 플랫폼별 빌드를 받을 수 있다.

OAuth 인증

Google 서비스에 접근하려면 OAuth 인증이 필요하다. CLI가 브라우저를 열어 인증 흐름을 처리한다.

# 인증 시작 (브라우저가 열림)
gws auth login

# 인증 상태 확인
gws auth status

# 여러 계정 관리
gws auth login --account work@example.com
gws auth switch work@example.com

인증 토큰은 로컬에 안전하게 저장된다. 한 번 인증하면 이후 명령어를 실행할 때마다 재인증이 필요 없다.

프로젝트 설정

특정 프로젝트 디렉토리에서 기본 계정이나 설정을 고정하고 싶다면 .gws.toml 파일을 만든다.

# .gws.toml
[auth]
default_account = "work@example.com"

[gmail]
default_labels = ["INBOX", "UNREAD"]

[drive]
default_format = "json"

---

핵심 명령어 실전 가이드

Gmail 자동화

이메일 관리는 1인 개발자가 가장 많은 시간을 쓰는 영역 중 하나다. gws gmail 명령어로 이 시간을 줄인다.

# 받은 편지함 목록 (최근 10개)
gws gmail list --max-results 10

# 읽지 않은 이메일만
gws gmail list --query "is:unread"

# 특정 발신자 이메일 검색
gws gmail list --query "from:client@example.com"

# 이메일 본문 읽기
gws gmail get --id MESSAGE_ID

# 이메일 전송
gws gmail send \
  --to "client@example.com" \
  --subject "프로젝트 업데이트" \
  --body "안녕하세요. 이번 주 진행 상황을 공유드립니다."

# 파일 첨부
gws gmail send \
  --to "client@example.com" \
  --subject "보고서" \
  --body "첨부 파일 확인 부탁드립니다." \
  --attachment ./report.pdf

# 이메일 라벨 추가
gws gmail label --id MESSAGE_ID --add "중요고객"

# 이메일 아카이브
gws gmail archive --id MESSAGE_ID

Google Drive 파일 관리

# 파일 목록 조회
gws drive list

# 특정 폴더 내 파일
gws drive list --folder-id FOLDER_ID

# 파일 검색
gws drive list --query "name contains '보고서'"

# 파일 다운로드
gws drive download --id FILE_ID --output ./local-file.pdf

# 파일 업로드
gws drive upload --file ./report.pdf --folder-id FOLDER_ID

# 파일 정보 조회
gws drive get --id FILE_ID

# 파일 공유 설정
gws drive share --id FILE_ID --email colleague@example.com --role reader

# 폴더 생성
gws drive mkdir --name "2026년 프로젝트" --parent-id PARENT_FOLDER_ID

Google Calendar 일정 관리

# 오늘 일정 조회
gws calendar events --time-min "$(date -u +%Y-%m-%dT00:00:00Z)" --time-max "$(date -u +%Y-%m-%dT23:59:59Z)"

# 이번 주 일정
gws calendar events --days 7

# 새 일정 생성
gws calendar create \
  --summary "클라이언트 미팅" \
  --start "2026-03-20T10:00:00+09:00" \
  --end "2026-03-20T11:00:00+09:00" \
  --attendees client@example.com

# 일정 목록 (JSON 출력)
gws calendar events --format json

# 캘린더 목록 조회
gws calendar list

Google Sheets 데이터 처리

# 스프레드시트 읽기
gws sheets read --id SPREADSHEET_ID --range "Sheet1!A1:D10"

# 데이터 쓰기
gws sheets write \
  --id SPREADSHEET_ID \
  --range "Sheet1!A1" \
  --values "날짜,매출,비용,순이익"

# 행 추가
gws sheets append \
  --id SPREADSHEET_ID \
  --range "Sheet1" \
  --values "2026-03-16,500000,100000,400000"

# 스프레드시트 목록
gws sheets list

---

AI 에이전트와의 통합: AGENTS.md의 힘

Google Workspace CLI의 가장 차별화된 기능은 AGENTS.md 내장이다. 이게 왜 중요한지 이해하려면 AI 에이전트가 도구를 어떻게 학습하는지 알아야 한다.

Claude Code, Cursor, GitHub Copilot 같은 AI 에이전트는 프로젝트 디렉토리의 AGENTS.md(또는 CLAUDE.md) 파일을 읽어 해당 프로젝트에서 사용 가능한 도구와 작업 방식을 학습한다. Google Workspace CLI는 이 파일을 기본적으로 제공해, 에이전트가 별도 학습 없이 Gmail 송수신, Drive 파일 조작, Calendar 일정 관리를 자동으로 수행할 수 있게 한다.

Claude Code와 연동

프로젝트 루트의 CLAUDE.md에 다음을 추가한다.

## Google Workspace 도구

이 프로젝트에서 `gws` CLI를 사용해 구글 서비스를 제어할 수 있다.

### 가능한 작업
- 이메일 전송: `gws gmail send --to EMAIL --subject SUBJECT --body BODY`
- 파일 업로드: `gws drive upload --file PATH --folder-id FOLDER_ID`
- 일정 생성: `gws calendar create --summary TITLE --start START --end END`

### 계정
- 기본 계정: work@yourdomain.com
- Drive 루트 폴더 ID: YOUR_FOLDER_ID

이렇게 설정하면 Claude Code에게 "오늘 작업 완료된 보고서를 Drive에 올리고 클라이언트에게 이메일 보내줘"라고 말하면 에이전트가 직접 CLI를 실행한다.

자동화 스크립트와 AI 조합

#!/bin/bash
# daily-report.sh — AI가 생성한 보고서를 자동 전송하는 스크립트

# 1. 오늘 일정 조회
TODAY_EVENTS=$(gws calendar events --days 1 --format json)

# 2. AI로 일일 요약 생성 (Claude CLI 연동)
SUMMARY=$(echo "$TODAY_EVENTS" | claude --print "오늘 일정을 한국어로 요약해줘")

# 3. 요약을 이메일로 전송
gws gmail send \
  --to "myself@example.com" \
  --subject "오늘의 일정 요약 $(date +%Y-%m-%d)" \
  --body "$SUMMARY"

echo "일일 요약 전송 완료"

---

1인 개발자 실전 워크플로우

아침 루틴 자동화

1인 개발자의 아침은 정보 수집으로 시작된다. 이걸 자동화하면 커피 한 잔 마시는 동안 모든 정보가 준비된다.

#!/bin/bash
# morning-brief.sh

echo "=== 오늘의 브리핑 ==="

# 오늘 일정
echo "\n📅 오늘 일정:"
gws calendar events --days 1 --format json | \
  jq -r '.[] | "\(.start.dateTime | split("T")[1] | split("+")[0]) - \(.summary)"'

# 읽지 않은 중요 이메일
echo "\n📧 읽지 않은 이메일 (${#emails[@]}개):"
gws gmail list --query "is:unread is:important" --max-results 5 --format json | \
  jq -r '.[] | "[\(.from)] \(.subject)"'

# 최근 Drive 파일 변경
echo "\n📁 최근 변경된 파일:"
gws drive list --query "modifiedTime > '$(date -d 'yesterday' +%Y-%m-%dT%H:%M:%SZ)'" --format json | \
  jq -r '.[] | "\(.name) (\(.modifiedTime | split("T")[0]))"'

echo "\n브리핑 완료!"

이 스크립트를 cron에 등록하거나 터미널 시작 시 자동 실행하도록 설정한다.

# crontab -e
# 매일 오전 9시 실행
0 9 * * * /path/to/morning-brief.sh >> ~/logs/morning-brief.log 2>&1

고객 이메일 자동 응답 시스템

고객 이메일에 빠르게 응답하는 건 1인 개발자의 핵심 경쟁력이다. AI와 CLI를 조합해 초안을 자동 생성한다.

#!/bin/bash
# auto-draft-reply.sh

# 읽지 않은 이메일 목록 가져오기
UNREAD_EMAILS=$(gws gmail list \
  --query "is:unread from:client" \
  --format json \
  --max-results 5)

# 각 이메일에 대해 AI 초안 생성
echo "$UNREAD_EMAILS" | jq -c '.[]' | while read -r email; do
  EMAIL_ID=$(echo "$email" | jq -r '.id')
  SUBJECT=$(echo "$email" | jq -r '.subject')
  SNIPPET=$(echo "$email" | jq -r '.snippet')

  echo "이메일 처리 중: $SUBJECT"

  # AI로 답장 초안 생성
  DRAFT=$(echo "제목: $SUBJECT\n내용 요약: $SNIPPET" | \
    claude --print "이 고객 이메일에 대한 전문적인 한국어 답장을 작성해줘. 200자 이내로")

  # 임시 파일에 저장 (검토 후 전송)
  echo "$DRAFT" > "/tmp/draft_${EMAIL_ID}.txt"
  echo "초안 저장됨: /tmp/draft_${EMAIL_ID}.txt"
done

프로젝트 파일 자동 백업

#!/bin/bash
# backup-to-drive.sh

PROJECT_DIR="$HOME/projects/my-app"
BACKUP_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
DATE=$(date +%Y-%m-%d)

# 프로젝트 압축
tar -czf "/tmp/backup-${DATE}.tar.gz" \
  --exclude="node_modules" \
  --exclude=".git" \
  "$PROJECT_DIR"

# Drive에 업로드
gws drive upload \
  --file "/tmp/backup-${DATE}.tar.gz" \
  --folder-id "$BACKUP_FOLDER_ID" \
  --name "backup-${DATE}.tar.gz"

# 로컬 임시 파일 정리
rm "/tmp/backup-${DATE}.tar.gz"

echo "백업 완료: backup-${DATE}.tar.gz → Google Drive"

매출 추적 스프레드시트 자동 업데이트

SaaS나 디지털 제품을 판매한다면 매출 데이터를 자동으로 기록하는 게 유용하다.

#!/bin/bash
# record-revenue.sh
# 사용법: ./record-revenue.sh "결제수단" "금액" "제품명"

SPREADSHEET_ID="YOUR_SPREADSHEET_ID"
DATE=$(date +%Y-%m-%d)
PAYMENT_METHOD=$1
AMOUNT=$2
PRODUCT=$3

# 스프레드시트에 행 추가
gws sheets append \
  --id "$SPREADSHEET_ID" \
  --range "매출기록" \
  --values "${DATE},${PAYMENT_METHOD},${AMOUNT},${PRODUCT}"

echo "매출 기록됨: ${DATE} | ${PRODUCT} | ${AMOUNT}원"

# 이달 매출 합계 계산
gws sheets read \
  --id "$SPREADSHEET_ID" \
  --range "매출기록!C:C" \
  --format json | \
  jq '[.[] | tonumber] | add' | \
  xargs -I{} echo "이달 누적 매출: {}원"

---

보안 및 주의사항

팀 환경 주의사항: 팀 환경에서는 서비스 계정(Service Account) 인증을 사용하는 게 더 안전하다. 개인 계정 OAuth 토큰을 서버에 저장하면 계정 보안에 리스크가 생긴다.

# 서비스 계정 인증 (팀/서버 환경)
gws auth login --service-account /path/to/service-account.json

스코프 최소화: 인증 시 필요한 권한만 요청한다. Gmail만 사용한다면 Drive, Calendar 권한은 요청하지 않는다.

# 특정 스코프만 인증
gws auth login --scopes gmail.readonly,gmail.send

---

가격과 제한

Google Workspace CLI 자체는 완전 무료 오픈소스다. Apache 2.0 라이선스로 상업적 사용도 가능하다.

단, Google Workspace 서비스를 사용하려면 Google 계정이 필요하다. 개인 Gmail 계정은 무료로 사용 가능하지만, 비즈니스용 Google Workspace(구 G Suite) 구독은 별도다.

플랜	가격	주요 기능
Google Workspace Starter	월 $6/유저	Gmail, Drive 30GB, Meet
Business Standard	월 $12/유저	Drive 2TB, 녹화 기능
Business Plus	월 $18/유저	Drive 5TB, 고급 보안

1인 개발자라면 개인 Gmail 계정으로 시작해 필요에 따라 Workspace 구독을 추가하는 게 합리적이다. CLI 자체는 무료이므로 Google 계정만 있으면 바로 시작할 수 있다.

API 할당량: Google API는 일일 호출 횟수 제한이 있다. 개인 프로젝트 수준에서는 거의 도달하지 않지만, 대량 자동화 작업을 계획한다면 Google Cloud Console에서 할당량을 확인한다.

---

CLI 도구 생태계에서의 위치

Google Workspace CLI는 독립 실행형 도구가 아니다. 다른 CLI 도구들과 조합할 때 진짜 가치가 나온다.

조합 예시:

• gws + jq: JSON 파싱으로 데이터 필터링
• gws + claude (Claude Code CLI): AI 에이전트가 이메일 초안 생성 → gws gmail send로 전송
• gws + gh (GitHub CLI): PR 머지 알림 이메일 자동 처리
• gws + curl (Webhook): Slack/Discord 알림과 연동

이 조합이 강력한 이유는 모두 JSON을 다루는 CLI이기 때문이다. 파이프로 연결하고 jq로 변환하면 어떤 도구끼리도 통합된다.

---

현재 한계와 로드맵

2026년 3월 출시된 초기 버전이다 보니 몇 가지 한계가 있다.

현재 지원 서비스: Gmail, Drive, Calendar, Sheets, Docs (읽기 전용), Admin SDK

미지원 기능:

• Google Meet 미팅 생성 (아직 API 통합 없음)
• Google Forms 생성/편집
• Workspace Chat 메시지 송수신

알려진 이슈: Windows에서 OAuth 인증 흐름이 간헐적으로 실패하는 케이스가 보고됨. Linux/macOS 환경 권장.

GitHub 이슈 트래커를 보면 커뮤니티가 활발하게 기여하고 있어 빠르게 개선될 것으로 보인다.

---

결론: 터미널이 당신의 생산성 허브가 된다

Google Workspace CLI는 개발자가 이미 익숙한 터미널 환경에서 이메일, 파일, 일정을 처리할 수 있게 한다. 브라우저 탭을 오가는 컨텍스트 스위칭이 줄어들고, 스크립트로 반복 작업을 자동화할 수 있으며, AI 에이전트가 이 도구를 직접 활용해 더 복잡한 워크플로우를 처리한다.

AGENTS.md 내장이 특히 중요하다. 단순히 "CLI가 있다"를 넘어, "AI 에이전트가 이 CLI를 사용하는 방법을 이미 안다"는 뜻이다. Claude Code에게 "지난 일주일 동안 온 고객 이메일을 분류해서 스프레드시트에 정리해줘"라고 말하면 에이전트가 gws gmail list, gws sheets append를 직접 실행한다.

1인 개발자에게 시간은 가장 희소한 자원이다. 반복 작업을 자동화하고, AI 에이전트에게 위임하고, 자신은 핵심 의사결정에 집중하는 것 — Google Workspace CLI는 그 흐름을 만드는 데 실질적인 도움이 된다.

# 지금 바로 시작
cargo install gws
gws auth login
gws gmail list --max-results 5

터미널에서 Gmail을 처음 확인하는 순간, 이 도구의 가치를 체감하게 될 것이다.