Google Workspace CLI로 구글 서비스 터미널에서 제어하기

Google Workspace CLI로 구글 서비스 터미널에서 제어하기

구글 드라이브에서 파일 찾고, 지메일로 메일 보내고, 캘린더에 일정 추가하고, 시트에 데이터 넣는 작업을 매번 브라우저 열어서 하고 계신가요? 터미널 명령어 한 줄이면 이걸 다 할 수 있다면요? 🤔

오늘 소개할 gws(Google Workspace CLI)가 바로 그런 도구입니다. 구글 Discovery Service를 기반으로 명령어를 동적 생성하기 때문에 구글 API가 업데이트되면 도구를 따로 업데이트하지 않아도 새 기능을 바로 쓸 수 있는데요. AI 에이전트 연동까지 고려해서 설계됐기 때문에 자동화 워크플로우에도 딱입니다.

gws란?

gws는 Google Workspace 서비스를 하나의 CLI로 묶어놓은 도구입니다. 레포지토리 소개 문구가 성격을 잘 드러내는데요.

One CLI for all of Google Workspace — built for humans and AI agents.

Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin까지 터미널에서 바로 다룰 수 있고요. 응답이 전부 JSON이라 jq로 원하는 데이터만 뽑아내기 좋고, 셸 스크립트에서 파싱하기도 편합니다.

참고로 이 프로젝트는 구글의 공식 제품이 아닙니다. “This is not an officially supported Google product”라는 안내가 붙어 있고, v1.0을 향해 한창 개발 중이라 호환성이 깨지는 변경이 생길 수 있다는 점은 감안해야 합니다.

설치

npm으로 전역 설치하는 게 제일 간단합니다.

npm install -g @googleworkspace/cli

macOS 사용자라면 Homebrew로도 설치할 수 있습니다.

brew install googleworkspace-cli

Rust로 만들어졌기 때문에 Cargo로 소스 빌드도 되고, GitHub Releases에서 플랫폼별 바이너리를 받아도 됩니다. Nix 쓰시는 분은 github:googleworkspace/cli 플레이크도 있고요.

설치 후 잘 되었는지 확인해봅시다.

gws --help

인증 설정

gws를 쓰려면 먼저 구글 API 인증 설정을 해야 합니다. 방법이 여러 가지인데 상황에 맞게 고르면 됩니다.

제일 편한 방법은 gws auth setup 명령어입니다. Google Cloud 프로젝트 생성부터 OAuth 설정까지 알아서 해주는데, gcloud CLI가 미리 설치되어 있어야 합니다.

gws auth setup

명령어를 실행하면 5단계를 순서대로 진행합니다.

먼저 gcloud CLI가 설치되어 있는지 확인한 뒤, 사용할 구글 계정을 고릅니다. gcloud에 로그인된 계정이 목록에 표시되고, 새 계정으로 로그인할 수도 있습니다.

┌ gws auth setup ─────────────────────────────────────────────────┐
│  ✓ Step 1/5: gcloud CLI — found                                │
│  ▸ Step 2/5: Authentication                                     │
│  ○ Step 3/5: GCP project                                        │
│  ○ Step 4/5: Workspace APIs                                     │
│  ○ Step 5/5: OAuth credentials                                  │
└─────────────────────────────────────────────────────────────────┘
┌ Select a Google account ────────────────────────────────────────┐
│   ○ ➕ Login with new account                                   │
│ ▸ ◉ user@gmail.com                                              │
└─────────────────────────────────────────────────────────────────┘

다음으로 Google Cloud 프로젝트를 선택합니다. 기존 프로젝트 목록에서 고르거나, 새 프로젝트를 만들 수도 있습니다.

┌ gws auth setup ─────────────────────────────────────────────────┐
│  ✓ Step 1/5: gcloud CLI — found                                │
│  ✓ Step 2/5: Authentication — user@gmail.com                    │
│  ▸ Step 3/5: GCP project                                        │
│  ○ Step 4/5: Workspace APIs                                     │
│  ○ Step 5/5: OAuth credentials                                  │
└─────────────────────────────────────────────────────────────────┘
┌ Select a GCP project ──────────────────────────────────────────┐
│   ○ ➕ Create new project                                      │
│   ○ ⌨ Enter project ID manually                                │
│ ▸ ◉ my-project  My Project                                     │
│   ○ ...                                                        │
└─────────────────────────────────────────────────────────────────┘

그 다음 사용할 Google Workspace API를 고릅니다. 이미 프로젝트에서 활성화된 API는 (already enabled)로 표시됩니다.

┌ gws auth setup ─────────────────────────────────────────────────┐
│  ✓ Step 1/5: gcloud CLI — found                                │
│  ✓ Step 2/5: Authentication — user@gmail.com                    │
│  ✓ Step 3/5: GCP project — my-project                           │
│  ▸ Step 4/5: Workspace APIs                                     │
│  ○ Step 5/5: OAuth credentials                                  │
└─────────────────────────────────────────────────────────────────┘
┌ Select APIs to enable  5/22 selected ───────────────────────────┐
│ ▸ ◉ Google Drive  drive.googleapis.com (already enabled)        │
│   ○ Google Sheets  sheets.googleapis.com                        │
│   ◉ Gmail  gmail.googleapis.com (already enabled)               │
│   ◉ Google Calendar  calendar-json.googleapis.com (already enabled) │
│   ◉ Google Docs  docs.googleapis.com (already enabled)          │
│   ○ Google Slides  slides.googleapis.com                        │
│   ○ Google Tasks  tasks.googleapis.com                          │
│   ◉ People (Contacts)  people.googleapis.com (already enabled)  │
│   ...                                                           │
└─────────────────────────────────────────────────────────────────┘

스페이스바로 원하는 API를 선택/해제하고 엔터를 누르면, 마지막 단계에서 OAuth 클라이언트 설정 화면이 나옵니다.

┌ gws auth setup ─────────────────────────────────────────────────┐
│  ✓ Step 1/5: gcloud CLI — found                                │
│  ✓ Step 2/5: Authentication — user@gmail.com                    │
│  ✓ Step 3/5: GCP project — my-project                           │
│  ✓ Step 4/5: Workspace APIs — 0 enabled, 5 skipped             │
│  ▸ Step 5/5: OAuth credentials — Waiting for manual input...    │
│                                                                 │
│  Manual OAuth client setup required.                            │
│                                                                 │
│  Step A — Consent screen (if not configured):                   │
│  https://console.cloud.google.com/apis/credentials/consent      │
│  → User Type: External, then save through all screens.          │
│                                                                 │
│  Step B — Create an OAuth client:                               │
│  https://console.cloud.google.com/apis/credentials              │
│  → 'Create Credentials' → 'OAuth client ID'                    │
│  → Application type: Desktop app                                │
│                                                                 │
│  Copy the Client ID and Client Secret from the dialog,          │
│  then paste them below.                                         │
└─────────────────────────────────────────────────────────────────┘
┌ Enter OAuth Client ID ──────────────────────────────────────────┐
│ > █                                                             │
└─────────────────────────────────────────────────────────────────┘

Google Cloud Console에서 OAuth 동의 화면을 구성하고 OAuth 클라이언트 ID를 만든 뒤, Client ID와 Client Secret을 차례로 입력합니다. OAuth 설정이 처음이라면 OAuth 2.0으로 구글 API 호출하기를 먼저 읽어보시는 것도 좋습니다.

그러면 OAuth 스코프를 고르는 화면이 나옵니다.

Select OAuth scopes  38/57 selected
────────────────────────────────────────────────────────────────────
  [x] ✨ Recommended (Core Consumer Scopes)
  [ ] 🔒 Read Only
  [ ] ⚠️ Full Access (All Scopes)
  [ ] drive            ⛔ RESTRICTED  See, edit, create, and delete all of your Google Drive files
  [x] drive.readonly   ⛔ RESTRICTED  See and download all your Google Drive files
  [x] gmail.readonly   ⛔ RESTRICTED  View your email messages and settings
  [x] gmail.send       ⚠️  SENSITIVE  Send email on your behalf
  [x] documents        ⚠️  SENSITIVE  See, edit, create, and delete all your Google Docs documents
  [x] calendar         See, edit, share, and permanently delete all the calendars
  [x] contacts         See, edit, download, and permanently delete your contacts
  [x] userinfo.email   See your primary Google Account email address
  [x] userinfo.profile See your personal info
  ...
────────────────────────────────────────────────────────────────────
 ↑↓ Navigate   Space Toggle   a All   Enter Confirm   Esc Cancel

맨 위 세 가지 프리셋 중 하나를 고르면 아래 개별 스코프의 체크 상태가 자동으로 바뀝니다.

  • ✨ Recommended — API당 핵심 스코프 하나씩만 선택
  • 🔒 Read Only*.readonly 스코프만 선택
  • ⚠️ Full Access — 쓰기 포함 모든 스코프 선택

프리셋을 기반으로 개별 스코프를 추가하거나 빼는 것도 가능합니다. 개인 용도라면 ✨ Recommended로 시작하는 게 무난합니다. 엔터를 누르면 바로 로그인할지 물어보고, Y를 선택하면 설정 결과가 출력된 뒤 브라우저에서 구글 OAuth 로그인이 진행됩니다.

Run `gws auth login` now? [Y/n]:
{
  "account": "user@gmail.com",
  "apis_enabled": 0,
  "apis_skipped": 5,
  "client_config": "/Users/user/.config/gws/client_secret.json",
  "message": "Setup complete! Starting `gws auth login`...",
  "project": "my-project",
  "status": "success"
}

✅ Setup complete! Starting `gws auth login`...
Open this URL in your browser to authenticate:

  https://accounts.google.com/o/oauth2/auth?...

브라우저에서 링크를 열면 “Google hasn’t verified this app”이라는 경고 화면이 나올 수 있습니다. 직접 만든 OAuth 클라이언트라 구글의 검증을 거치지 않아서 뜨는 건데, “Continue”를 눌러서 진행하면 됩니다. 구글 계정 로그인과 권한 동의를 마치면 인증이 완료되고 결과가 출력됩니다.

{
  "account": "user@gmail.com",
  "credentials_file": "/Users/user/.config/gws/credentials.enc",
  "encryption": "AES-256-GCM (key in OS keyring or local `.encryption_key`)",
  "message": "Authentication successful. Encrypted credentials saved.",
  "scopes": [
    "https://www.googleapis.com/auth/drive",
    "https://www.googleapis.com/auth/gmail.modify",
    "https://www.googleapis.com/auth/documents",
    "https://www.googleapis.com/auth/calendar",
    ...
  ],
  "status": "success"
}

서비스 계정을 사용하는 경우에는 환경 변수로 인증 파일 경로를 지정합니다.

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json

이미 액세스 토큰을 가지고 있다면 환경 변수에 직접 넣어서 사용할 수도 있습니다.

export GOOGLE_WORKSPACE_CLI_TOKEN="ya29.a0AfH6SM..."

헤드리스 서버처럼 브라우저를 열 수 없는 환경에서는 다른 머신에서 인증을 마친 후 자격 증명을 export/import하는 방법도 있습니다.

한 가지 주의할 게 있는데요. 테스트 모드(미인증) OAuth 앱은 동의 화면에서 스코프를 약 25개까지만 허용합니다. gws 권장 스코프 프리셋이 이 제한을 넘기 때문에, 실제로 쓸 서비스만 골라서 스코프를 잡는 게 좋습니다.

Gmail로 메일 관리하기

인증이 끝났으면 바로 써볼까요? 아마 가장 많이 쓰게 될 Gmail부터 시작합니다.

읽지 않은 메일을 조회하려면 이렇게 하면 됩니다. userId"me"를 넣으면 현재 인증된 사용자의 메일함을 대상으로 합니다.

gws gmail users messages list --params '{"userId": "me", "q": "is:unread"}'

q 파라미터에는 Gmail 검색 문법을 그대로 쓸 수 있어서, 특정 발신자나 기간으로 필터링하는 것도 간단합니다.

gws gmail users messages list --params '{"userId": "me", "q": "from:github.com after:2025/03/01"}'

메일을 아카이브하려면 modify 명령어로 INBOX 라벨을 제거하면 됩니다.

gws gmail users messages modify \
  --params '{"userId": "me", "id": "MESSAGE_ID"}' \
  --json '{"removeLabelIds": ["INBOX"]}'

읽음 처리도 같은 방식입니다. UNREAD 라벨을 제거하면 되고요.

gws gmail users messages modify \
  --params '{"userId": "me", "id": "MESSAGE_ID"}' \
  --json '{"removeLabelIds": ["UNREAD"]}'

메일을 휴지통으로 보내거나 복구하는 것도 한 줄이면 됩니다.

gws gmail users messages trash --params '{"userId": "me", "id": "MESSAGE_ID"}'
gws gmail users messages untrash --params '{"userId": "me", "id": "MESSAGE_ID"}'

라벨 목록을 확인하고 싶다면 이렇게 합니다.

gws gmail users labels list --params '{"userId": "me"}'

Calendar 일정 관리하기

캘린더에서 앞으로의 일정을 가져오는 것도 직관적입니다. calendarId"primary"로 지정하면 기본 캘린더의 일정을 조회합니다.

gws calendar events list --params '{"calendarId": "primary", "maxResults": 5}'

날짜 범위를 지정하고 싶다면 timeMintimeMax 파라미터를 추가하면 됩니다.

gws calendar events list \
  --params '{"calendarId": "primary", "timeMin": "2025-03-01T00:00:00Z", "timeMax": "2025-03-31T23:59:59Z"}'

일정을 만들 때는 insert 명령어를 사용합니다.

gws calendar events insert \
  --params '{"calendarId": "primary"}' \
  --json '{"summary": "팀 미팅", "start": {"dateTime": "2025-03-25T14:00:00+09:00"}, "end": {"dateTime": "2025-03-25T15:00:00+09:00"}}'

quickAdd를 쓰면 자연어로 일정을 추가할 수도 있습니다.

gws calendar events quickAdd --params '{"calendarId": "primary", "text": "내일 오후 3시 커피챗"}'

일정 삭제도 간단합니다.

gws calendar events delete --params '{"calendarId": "primary", "eventId": "EVENT_ID"}'

Drive 파일 다루기

구글 드라이브에서 최근 파일 10개를 가져오려면 이렇게 하면 됩니다.

gws drive files list --params '{"pageSize": 10}'

파일이 많을 때는 --page-all 플래그로 자동 페이지네이션을 할 수 있는데요. jq와 조합하면 파일 이름만 깔끔하게 뽑아낼 수 있습니다.

gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'

파일 업로드도 간단합니다. --upload 플래그에 로컬 파일 경로를 지정하면 멀티파트 업로드가 자동으로 처리됩니다.

gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf

특정 폴더에 업로드하고 싶다면 parents 필드에 폴더 ID를 넣어주면 됩니다.

gws drive files create \
  --json '{"name": "data.csv", "parents": ["FOLDER_ID"]}' \
  --upload ./data.csv

Sheets 스프레드시트 만들기

스프레드시트를 새로 만드는 것도 한 줄이면 충분합니다.

gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

기존 스프레드시트에서 데이터를 읽거나 업데이트하는 것도 비슷한 패턴입니다. 스프레드시트 ID와 범위만 넣어주면 되고요.

Chat 메시지 보내기

Google Chat 스페이스에 메시지를 보내는 것도 가능합니다.

gws chat spaces messages create \
  --params '{"parent": "spaces/SPACE_ID"}' \
  --json '{"text": "배포가 완료되었습니다."}'

실제 메시지를 보내기 전에 요청이 어떻게 구성되는지 확인하고 싶다면 --dry-run 플래그를 붙여보세요.

gws chat spaces messages create \
  --params '{"parent": "spaces/SPACE_ID"}' \
  --json '{"text": "테스트 메시지입니다."}' \
  --dry-run

--dry-run을 사용하면 실제 API 호출 없이 요청 내용만 확인할 수 있어서 실수를 방지하는 데 유용합니다.

스키마 확인하기

각 API 메서드가 어떤 파라미터를 받는지 궁금할 때는 schema 명령어를 사용합니다.

gws schema drive files list

이 명령어가 해당 메서드의 전체 스키마를 보여주기 때문에 별도의 API 문서를 뒤지지 않고도 어떤 파라미터를 넣어야 하는지 바로 확인할 수 있습니다. 새로운 API를 처음 사용할 때 특히 도움이 됩니다.

모든 리소스와 메서드에 --help 플래그를 붙이면 해당 명령어의 사용법도 바로 볼 수 있습니다.

gws drive files --help
gws gmail users messages --help

동적 명령어 생성의 비밀

gws가 재미있는 건 명령어가 하드코딩되어 있지 않다는 점입니다. 내부적으로 2단계 파싱 전략을 씁니다.

먼저 명령어에서 서비스 이름(예: drive, gmail)을 뽑아냅니다. 그러고 나서 해당 서비스의 Discovery Document를 구글 서버에서 받아와서(24시간 캐시) 명령어 트리를 그때그때 만듭니다. 나머지 인자를 파싱하고 인증을 거쳐 HTTP 요청을 날리는 거죠.

덕분에 구글이 새 API 엔드포인트를 추가하면 gws에서도 알아서 지원됩니다. 도구 자체를 업데이트 안 해도 새 기능을 바로 쓸 수 있다는 이야기입니다.

AI 에이전트와 연동하기

“built for humans and AI agents”라고 소개한 데는 이유가 있습니다.

일단 출력이 전부 JSON이니까 LLM이 파싱하기 좋습니다. 거기에 100개 넘는 Agent Skills(마크다운으로 작성된 워크플로우 정의)이 들어 있는데요. 네 가지 카테고리로 나뉩니다.

우선 서비스 스킬은 Drive, Gmail, Calendar, Sheets, Docs, Slides, Tasks, Chat, People, Admin, Classroom, Forms, Keep, Meet 등 구글 워크스페이스 API마다 하나씩 대응하는 스킬이 있어서 조합해서 쓸 수 있습니다.

그다음 페르소나 스킬은 Executive Assistant, Project Manager, HR Coordinator, Sales Ops, IT Admin, Content Creator, Customer Support, Event Coordinator, Team Lead, Researcher 같은 역할별 번들인데요. 역할에 필요한 서비스 스킬과 워크플로우 패턴이 미리 묶여 있어서, 어떤 스킬 조합이 필요한지 고민할 필요 없이 페르소나만 지정하면 됩니다.

헬퍼 스킬은 자주 쓰는 작업의 단축 명령어입니다. 파일 업로드(gws-drive-upload), 메일 발송(gws-gmail-send) 같은 것들이죠.

마지막으로 레시피 스킬은 외부 공유된 Drive 파일 감사, Sheets 데이터로 개인화된 메일 발송 같은 다단계 워크플로우가 실제 명령어와 함께 정리되어 있어서 복사해서 바로 쓸 수 있습니다.

에이전트 스킬이 뭔지 궁금하시다면 Agent Skills: AI를 위한 업무 매뉴얼을 참고하세요. 직접 만들어보고 싶으시다면 Agent Skill 만들기, 다른 사람이 만든 스킬을 찾아 쓰고 싶으시다면 skills.sh: 공개 에이전트 스킬 생태계를 읽어보시면 됩니다.

gws의 스킬을 다운로드하려면 저장소를 클론하거나, npx skills add로도 설치할 수 있습니다.

git clone https://github.com/googleworkspace/cli.git
npx skills add googleworkspace/cli

skills/ 디렉토리 안에 카테고리별로 마크다운 파일이 정리되어 있어서, 필요한 스킬만 골라 자신의 프로젝트에 복사해서 쓸 수 있습니다.

Gemini CLI 확장 기능으로 사용하려면 다음 명령어 한 줄이면 됩니다.

gemini extensions install https://github.com/googleworkspace/cli

OpenClaw 같은 에이전트 프레임워크와도 연동할 수 있는데요. README에 OpenClaw 설정 방법이 공식으로 포함되어 있을 정도로 에이전트 생태계를 의식한 도구입니다. Skills을 심링크로 연결하면 AI 에이전트가 구글 워크스페이스 작업을 직접 수행할 수 있고, gws-shared 스킬에는 gws가 없으면 npm으로 자동 설치하는 로직까지 들어 있어서 에이전트가 스스로 부트스트랩할 수 있습니다.

Claude Code에서도 활용할 수 있습니다. gws가 설치되어 있으면 Claude Code가 셸 명령어로 직접 호출할 수 있고, JSON 출력을 파싱해서 후속 작업까지 이어갈 수 있습니다. 더 강력한 방법은 gws에 내장된 MCP 서버를 쓰는 건데요.

gws mcp-server --services drive,gmail,calendar

이렇게 MCP 서버를 띄우면 Claude Desktop, VS Code, Gemini CLI 등 MCP 호환 클라이언트에서 구글 워크스페이스 API를 구조화된 도구로 쓸 수 있습니다. 서비스마다 10~80개의 도구가 추가되니까 실제로 쓸 서비스만 골라서 지정하는 게 좋습니다.

Model Armor 통합도 눈에 띄는데요. Google Cloud의 Model Armor로 응답을 에이전트에 전달하기 전에 프롬프트 인젝션 시도를 걸러낼 수 있습니다. warn 모드로 돌리면 의심스러운 내용에 플래그만 달고 그대로 전달하고, block 모드로 돌리면 아예 제거해버립니다. 에이전트가 처음 보는 메일이나 문서를 자율적으로 처리할 때 누군가 의도적으로 심어둔 프롬프트 인젝션을 방어할 수 있어서, 보안이 중요한 환경에서 쓸 만한 기능이죠.

실용적인 활용 팁

실무에서 gws를 쓸 때 알아두면 좋은 것들을 몇 가지 정리해봤습니다.

셸 스크립트와 조합하면 반복 작업을 금방 자동화할 수 있는데요. 매일 아침 오늘 일정과 안 읽은 메일 수를 터미널에 띄워주는 스크립트를 예로 들어볼게요.

today.sh
#!/bin/bash
echo "=== 오늘의 일정 ==="
gws calendar events list \
  --params "{\"calendarId\": \"primary\", \"timeMin\": \"$(date -u +%Y-%m-%dT00:00:00Z)\", \"timeMax\": \"$(date -u +%Y-%m-%dT23:59:59Z)\"}" \
  | jq -r '.items[] | "\(.start.dateTime) - \(.summary)"'

echo ""
echo "=== 읽지 않은 메일 ==="
gws gmail users messages list \
  --params '{"userId": "me", "q": "is:unread", "maxResults": 5}' \
  | jq -r '.messages | length | tostring + "개의 읽지 않은 메일"'

--page-all--page-delay를 같이 쓰면 API 속도 제한에 안 걸리게 페이지 사이에 쉬는 시간을 줄 수 있고, --page-limit으로 최대 페이지 수를 제한할 수도 있습니다. 데이터를 대량으로 긁어올 때 유용합니다.

환경 변수는 .env 파일에 넣어두면 매번 export 안 해도 됩니다.

.env
GOOGLE_WORKSPACE_CLI_TOKEN=ya29.a0AfH6SM...
GOOGLE_WORKSPACE_PROJECT_ID=my-project-123
GOOGLE_WORKSPACE_CLI_CONFIG_DIR=/custom/config/path

--dry-run은 앞에서도 언급했는데, 진짜 자주 쓰게 됩니다. 데이터를 만들거나 수정하는 작업은 --dry-run으로 먼저 확인하고 실행하는 습관을 들이면 실수가 확 줄어듭니다.

마치며

gws는 구글 워크스페이스 서비스를 터미널 하나로 묶어주는 도구입니다. Discovery Service 기반으로 명령어를 동적 생성하니까 구글 API 변경에 자동 대응하고, JSON 출력 덕분에 자동화 파이프라인에서 쓰기도 좋습니다.

아직 v1.0 전이라 바뀌는 부분이 있을 수 있지만, 터미널에서 구글 서비스를 자주 다루는 분이라면 한번 써볼 만합니다.

구글 API 인증이 처음이면 OAuth 2.0으로 구글 API 호출하기도 같이 읽어보세요.

This work is licensed under CC BY 4.0 CC BY

개발자를 위한 뉴스레터

달레가 정리한 AI 개발 트렌드와 직접 만든 콘텐츠를 전해드립니다.

Discord