구글 워크스페이스 CLI란? 6일 만에 화제가 된 이유

탄생 배경: “AI를 위해 CLI를 다시 써야 한다”

구글 워크스페이스 CLI(이하 gws)는 구글의 시니어 개발자 관계 엔지니어 Justin Poehnelt이 만든 오픈소스 프로젝트입니다. 그는 “기존 CLI는 사람을 위해 설계됐지만, AI 에이전트는 전혀 다른 것이 필요하다”는 철학을 바탕으로 이 도구를 만들었습니다. 핵심 아이디어는 단순합니다. Gmail, Drive, Calendar, Sheets, Docs, Chat, Admin — 구글 워크스페이스 전체를 터미널 명령어 하나로 통합하자는 것입니다.

왜 6일 만에 폭발적 반응이 나왔나

2026년 3월 5일 구글 클라우드 디렉터 Addy Osmani가 X(구 트위터)에 gws를 소개하자 즉시 수천 건의 리트윗이 달렸습니다. 개발자들이 흥분한 이유는 하나입니다. 기존에는 Zapier 같은 서드파티 커넥터를 깔고, 각 Workspace API를 개별로 연동하고, 유지보수 코드를 수십 줄 작성해야 했습니다. gws는 그 모든 과정을 npm install -g @googleworkspace/cli 한 줄로 대체합니다. 게다가 라이선스는 Apache 2.0으로 완전 무료입니다.

gws의 핵심 정체성: “인간과 AI 에이전트 모두를 위한 CLI”

GitHub 리포지터리 첫 줄은 이렇게 시작합니다. “One CLI for all of Google Workspace built for humans and AI agents.” 구조화된 JSON 출력, 100개 이상의 AI 에이전트 스킬, 50개의 업무 레시피가 기본 탑재되어 있습니다. 단순한 개발자 도구가 아니라, AI가 직접 구동하는 자율 업무 자동화의 첫 번째 공식 인터페이스라고 보면 됩니다.

▲ 목차로 돌아가기

gws가 기존 API 연동과 다른 결정적 차이

기존 방식의 3가지 고통

지금까지 개발자가 Google Workspace를 자동화하려면 세 가지 고통을 감수해야 했습니다. 첫째, Gmail API·Drive API·Calendar API를 각각 따로 설정하는 번거로움. 둘째, Zapier·n8n 같은 서드파티 커넥터 의존성과 그에 따른 추가 비용. 셋째, AI 에이전트가 API를 호출할 때마다 방대한 문서를 컨텍스트로 주입해야 해서 토큰 낭비가 극심했던 문제입니다. gws는 이 세 가지를 동시에 해결합니다.

동적 커맨드 빌드: 구글이 API 업데이트하면 gws도 자동 업데이트

gws는 하드코딩된 명령어 목록을 탑재하지 않습니다. 대신 구글의 Discovery Service를 런타임에 직접 읽어, 그 자리에서 전체 명령 체계를 동적으로 구성합니다. 이는 구글이 새 API 엔드포인트를 추가하는 즉시 gws에도 반영된다는 의미입니다. 정적으로 유지되는 도구 정의가 API 현실과 괴리되는 기존 문제를 근본적으로 차단합니다.

AI를 위한 설계 철학: JSON 페이로드 + 런타임 스키마 조회

사람 친화적 CLI는 플래그를 수십 개 늘어놓습니다. AI 에이전트는 그 플래그들을 학습하고 선택하는 과정에서 토큰을 낭비합니다. gws는 반대로 --json이나 --params 하나로 API 요청 본문을 그대로 전달합니다. 또한 gws schema drive.files.list처럼 특정 메서드의 스키마를 실시간으로 조회하면, 에이전트는 외부 문서 없이도 정확한 요청 구조를 파악합니다.

▲ 목차로 돌아가기

설치부터 인증까지: 5단계 완전 가이드

사전 준비물 체크리스트

gws를 쓰려면 세 가지가 필요합니다. Node.js 18 이상(또는 GitHub Releases의 사전 빌드 바이너리), Google Cloud 프로젝트(OAuth 자격증명 생성용), 그리고 Google Workspace 계정. gcloud CLI가 있으면 설정이 훨씬 빨라지지만 없어도 수동으로 진행할 수 있습니다.

npm install -g @googleworkspace/cli

gws auth setup

gws auth login -s drive,gmail,calendar

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

▲ 목차로 돌아가기

실전 명령어: Gmail·Drive·Calendar를 터미널로

Gmail: 최신 이메일 10개 조회 및 초안 작성

아래 명령어를 실행하면 최근 수신 이메일 ID 목록이 JSON으로 반환됩니다. AI 에이전트는 이 ID를 기반으로 각 메일의 발신자, 제목, 날짜를 자동 조회하고 요약합니다.

# 최신 이메일 10개 메시지 ID 조회
gws gmail users messages list --params '{"userId":"me","maxResults":10}'
# 특정 메일 상세 내용 조회
gws gmail users messages get --params '{"userId":"me","id":"MESSAGE_ID"}'
# Gmail 초안 생성 (base64 인코딩된 MIME 형식)
gws gmail users drafts create --params '{"userId":"me"}' \
--json '{"message":{"raw":"BASE64_ENCODED_MIME"}}'

Google Drive: 파일 목록·업로드·검색

Drive 명령어는 직관적입니다. 파일 목록 조회, PDF 업로드, 특정 키워드로 파일 검색까지 모두 터미널 한 줄로 처리됩니다. --page-all 플래그를 쓰면 페이지네이션 없이 전체 목록을 한 번에 받을 수 있습니다.

# 최근 10개 파일 목록
gws drive files list --params '{"pageSize":10}'
# PDF 파일 업로드
gws drive files create --json '{"name":"report.pdf"}' --upload ./report.pdf
# 전체 파일명 스트리밍 출력
gws drive files list --params '{"pageSize":100}' --page-all | jq -r '.files[].name'

Google Sheets & Calendar: 스프레드시트 생성 및 일정 관리

스프레드시트 생성과 데이터 추가도 JSON 페이로드 하나로 해결됩니다. Calendar 일정 생성 역시 동일한 방식이며, AI 에이전트가 자연어 요청을 받아 직접 일정을 만들어 주는 자동화가 가능해집니다. Sheets 범위 표현에 !가 포함될 때는 반드시 단일 인용부호로 감싸야 bash의 히스토리 확장 오류를 피할 수 있습니다.

# 스프레드시트 생성
gws sheets spreadsheets create --json '{"properties":{"title":"Q2 예산"}}'
# A1:C10 범위 데이터 읽기 (단일 인용부호 필수)
gws sheets spreadsheets values get \
--params '{"spreadsheetId":"SPREADSHEET_ID","range":"Sheet1!A1:C10"}'
# 데이터 행 추가
gws sheets spreadsheets values append \
--params '{"spreadsheetId":"ID","range":"Sheet1!A1","valueInputOption":"USER_ENTERED"}' \
--json '{"values":[["이름","점수"],["영효",95]]}'

▲ 목차로 돌아가기

AI 에이전트 연동: Gemini CLI·Claude Code·OpenClaw

Gemini CLI 익스텐션으로 연동하는 방법

가장 간단한 연동 방법은 Gemini CLI 익스텐션으로 gws를 설치하는 것입니다. 인증을 한 번만 완료해 두면 Gemini CLI 에이전트가 자동으로 자격증명을 상속받아 Google Workspace 전체를 제어합니다.

# 1. 먼저 gws 인증 완료
gws auth setup
# 2. Gemini CLI에 gws 익스텐션 설치
Claude Code & OpenClaw: MCP 서버 모드 활용

gws는 Gemini CLI 전용이 아닙니다. gws mcp 명령으로 MCP(Model Context Protocol) 서버 모드를 실행하면 Claude Desktop, VS Code, OpenClaw 등 MCP 호환 클라이언트에서도 동일하게 사용할 수 있습니다. Claude Code 사용자라면 OpenClaw 스킬 심링크 방식을 선호합니다.

# MCP 서버 모드 실행 (Claude Desktop, VS Code 등 연동)
gws mcp
# OpenClaw 스킬 전체 설치 (심링크 방식 — 자동 최신 동기화)
ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/
# 특정 스킬만 복사 설치
cp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/
100+ 에이전트 스킬이란 무엇인가

gws 리포지터리에는 100개가 넘는 SKILL.md 파일이 탑재되어 있습니다. 각 스킬은 지원되는 API 하나하나에 대응하며, 더 높은 수준의 복합 워크플로우 헬퍼와 Gmail·Drive·Docs·Calendar·Sheets에 걸친 50개의 큐레이션 레시피도 포함됩니다. AI 에이전트는 이 스킬 파일을 컨텍스트로 로딩해 커스텀 통합 레이어 없이도 즉시 복잡한 업무를 수행할 수 있습니다.


💡 전략적 통찰
gws가 단순한 CLI 도구로 끝나지 않는 이유는 Gemini CLI, Claude Code, OpenClaw 세 가지 AI 생태계를 동시에 지원하기 때문입니다. 특정 AI에 종속되지 않고, 어떤 에이전트든 Google Workspace를 제어할 수 있는 공통 레이어가 됩니다. 이것이 진짜 경쟁력입니다.

▲ 목차로 돌아가기