googleworkspace/cli

모든 Google Workspace를 위한 단일 CLI — 인간과 AI 에이전트(AI agents)를 위해 구축되었습니다.

Drive, Gmail, Calendar 및 모든 Workspace API를 지원합니다. 보일러플레이트(Boilerplate)가 없으며, 구조화된 JSON 출력을 제공합니다. 40개 이상의 에이전트 기술(agent skills)이 포함되어 있습니다.

참고

이것은 Google에서 공식적으로 지원하는 제품이 아닙니다.

gws는 정적인 명령 목록을 제공하지 않습니다. 런타임(runtime)에 Google 자체의 Discovery Service를 읽어 전체 명령 인터페이스를 동적으로 구축합니다. Google Workspace에 API 엔드포인트(endpoint)나 메서드(method)가 추가되면, gws는 이를 자동으로 감지합니다.

중요

이 프로젝트는 활발히 개발 중입니다. v1.0을 향해 나아가는 과정에서 파괴적 변경(breaking changes)이 발생할 수 있습니다.

• 사전 요구 사항 (Prerequisites)

• 설치 (Installation)

• 빠른 시작 (Quick Start)

• 왜 gws인가? (Why gws?)

• 인증 (Authentication)

• AI 에이전트 기술 (AI Agent Skills)

• 고급 사용법 (Advanced Usage)

• 환경 변수 (Environment Variables)

• 종료 코드 (Exit Codes)

• 아키텍처 (Architecture)

• 문제 해결 (Troubleshooting)

• 개발 (Development)

• Node.js 18+ — npm install을 위해 필요합니다. (또는 GitHub Releases에서 사전 빌드된 바이너리(pre-built binary)를 다운로드하세요)

• Google Cloud 프로젝트 — OAuth 자격 증명(credentials)을 위해 필요합니다. Google Cloud Console, gcloud CLI 또는 gws auth setup 명령어를 통해 생성할 수 있습니다.

• Google Workspace에 접근 권한이 있는 Google 계정

gws를 설치하는 권장 방법은 GitHub Releases 페이지에서 사용 중인 OS 및 아키텍처에 맞는 사전 빌드된 바이너리를 다운로드하는 것입니다. 압축을 풀고 gws 바이너리를 $PATH에 배치하세요.

편의를 위해 npm을 사용하여 GitHub Releases에서 적절한 바이너리를 자동으로 다운로드할 수도 있습니다:

npm install -g @googleworkspace/cli

또는 소스에서 빌드하세요:

cargo install --git https://github.com/googleworkspace/cli --locked

Nix flake는 github:googleworkspace/cli에서 사용할 수 있습니다.

nix run github:googleworkspace/cli

macOS 및 Linux에서는 Homebrew를 통해 설치할 수도 있습니다:

brew install googleworkspace-cli

gws auth setup # Google Cloud 프로젝트 설정을 안내합니다
gws auth login # 이후의 OAuth 로그인
gws drive files list --params '{"pageSize": 5}'

인간을 위해 — REST 문서에 맞춰 curl 호출을 작성하는 일을 멈추세요. gws는 --help를 제공합니다.

모든 리소스에 대해 --dry-run을 사용하여 요청을 미리 보고, 자동 페이지네이션 (auto-pagination)을 지원합니다.

AI 에이전트를 위해 — 모든 응답은 구조화된 JSON (structured JSON) 형식입니다. 포함된 에이전트 기술 (agent skills)과 결합하면, 별도의 커스텀 도구 없이도 LLM이 Workspace를 관리할 수 있습니다.

# 최근 파일 10개 목록 표시
gws drive files list --params '{"pageSize": 10}'
# 스프레드시트 생성
...

이 CLI는 다양한 인증 워크플로 (auth workflows)를 지원하므로 노트북, CI, 그리고 서버에서 모두 작동합니다.

보유 중인 상태…	사용 방법
gcloud가 설치되어 있고 인증됨	gws auth setup (가장 빠름)
GCP 프로젝트는 있지만 gcloud는 없음	수동 OAuth 설정
기존 OAuth 액세스 토큰이 있음	GOOGLE_WORKSPACE_CLI_TOKEN
기존 자격 증명 (Credentials)이 있음	GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE

자격 증명은 OS 키링 (keyring) (또는 GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file 설정 시 ~/.config/gws/.encryption_key)에 저장된 키를 사용하여 저장 시 암호화 (AES-256-GCM)됩니다.

gws auth setup # 1회성: Cloud 프로젝트 생성, API 활성화, 로그인 수행
gws auth login # 이후 범위 (scope) 선택 및 로그인

gws auth setup을 실행하려면 gcloud CLI가 필요합니다. gcloud가 없다면 대신 아래의 수동 설정을 사용하세요.

⚠️ 경고

테스트 모드에서의 범위 (Scope) 제한: OAuth 앱이 미검증 상태(테스트 모드)인 경우, Google은 동의 범위를 약 25개로 제한합니다. recommended 범위 프리셋은 85개 이상의 범위를 포함하고 있으므로, 미검증 앱(특히 @gmail.com 계정)에서는 실패하게 됩니다. 범위 선택기를 필터링하려면 대신 개별 서비스를 선택하세요:

gws auth login -s drive,gmail,sheets

gws auth setup이 프로젝트/클라이언트 생성을 자동화할 수 없거나, 명시적인 제어를 원하는 경우 이 방법을 사용하세요.

• 대상 프로젝트에서 Google Cloud Console을 엽니다:

• OAuth 동의 화면 (OAuth consent screen):
  https://console.cloud.google.com/apis/credentials/consent?project=<PROJECT_ID>

• 자격 증명 (Credentials):
  https://console.cloud.google.com/apis/credentials?project=<PROJECT_ID>

• OAuth 동의 화면:

• 프롬프트가 나타나면 OAuth 브랜딩/대상 (branding/audience)을 구성합니다:

• 앱 유형:
  External (테스트 모드도 괜찮습니다)

• 앱 유형 (App type):

• Test users (테스트 사용자) 아래에 귀하의 계정을 추가합니다 - OAuth 클라이언트 생성:

• 유형 (Type):
  Desktop app (데스크톱 앱)

• 유형 (Type):

• 클라이언트 JSON을 다운로드하여 다음 경로에 저장합니다:
  ~/.config/gws/client_secret.json

중요 (Important)

반드시 귀하 자신을 테스트 사용자 (test user)로 추가해야 합니다. OAuth 동의 화면 (OAuth consent screen)에서
Test users → Add users를 클릭하고 귀하의 Google 계정 이메일을 입력하세요. 이 과정을 거치지 않으면,
로그인이 일반적인 "Access blocked" (액세스 차단됨) 오류와 함께 실패합니다.

그 다음 다음 명령어를 실행합니다:

gws auth login

OAuth는 수동으로 완료하거나 브라우저 자동화 (browser automation)를 통해 완료할 수 있습니다.

사용자 흐름 (Human flow): gws auth login을 실행하고, 출력된 URL을 열어 권한 범위 (scopes)를 승인합니다. 에이전트 지원 흐름 (Agent-assisted flow): 에이전트가 URL을 열고, 계정을 선택하며, 동의 프롬프트를 처리한 뒤, localhost 콜백 (callback)이 성공하면 제어권을 반환합니다.

만약 동의 화면에 "Google hasn't verified this app" (Google에서 이 앱을 확인하지 않았습니다, 테스트 모드)라고 표시되면, Continue (계속)를 클릭하세요.
권한 범위 (scope) 체크박스가 나타나면, 계속하기 전에 필요한 권한을 선택하거나 (Select all) 모두 선택하세요.

• 브라우저가 있는 머신에서 대화형 인증 (interactive auth)을 완료합니다.

• 자격 증명 (credentials) 내보내기:
  gws auth export --unmasked > credentials.json

• 헤드리스 머신 (headless machine)에서:
  export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
gws drive files list # 바로 작동합니다

키 파일 (key file)을 가리키기만 하면 되며, 별도의 로그인은 필요하지 않습니다.

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
gws drive files list

다른 도구 (예: gcloud)가 이미 귀하의 환경을 위한 토큰을 발행(mints)하고 있는 경우 유용합니다.

export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)

우선순위 (Priority)	소스 (Source)	설정 방법 (Set via)
1	액세스 토큰 (Access token)	GOOGLE_WORKSPACE_CLI_TOKEN
...

환경 변수 (Environment variables)는 .env 파일에 저장할 수도 있습니다.

이 저장소는 100개 이상의 에이전트 스킬 (Agent Skills, SKILL.md 파일)을 제공합니다. 지원되는 모든 API에 대한 스킬 하나와, 일반적인 워크플로를 위한 상위 수준의 헬퍼 (helpers), 그리고 Gmail, Drive, Docs, Calendar, Sheets를 위한 50개의 큐레이션된 레시피 (recipes)가 포함되어 있습니다. 전체 목록은 전체 스킬 인덱스 (Skills Index)를 참조하세요.

# 모든 스킬을 한 번에 설치
npx skills add https://github.com/googleworkspace/cli
# 또는 필요한 것만 선택
...

OpenClaw 설정

# 모든 스킬을 심볼릭 링크(Symlink)로 연결 (레포지토리와 동기화 유지)
ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/
# 또는 특정 스킬만 복사
...

gws-shared 스킬에는 install 블록이 포함되어 있어, gws가 PATH에 설정되어 있지 않은 경우 OpenClaw가 npm을 통해 CLI를 자동으로 설치합니다.

먼저 CLI를 인증하세요:

gws auth setup

Gemini CLI에 확장을 설치하세요:

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

이 확장을 설치하면 Gemini CLI 에이전트가 모든 gws 명령어와 Google Workspace 에이전트 스킬에 직접 접근할 수 있습니다. gws는 자체적으로 인증을 안전하게 처리하므로, 에이전트를 사용하기 전에 터미널에서 한 번만 인증하면 확장 프로그램이 자동으로 사용자의 자격 증명 (credentials)을 상속받습니다.

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

플래그 (Flag)	설명	기본값
--page-all	자동 페이지 구분, 페이지당 하나의 JSON 라인 (NDJSON)	off
--page-limit <N>	가져올 최대 페이지 수	10
--page-delay <MS>	페이지 간 지연 시간	100 ms

Sheets 범위(ranges)에는 !가 사용되는데, 이는 bash에서 히스토리 확장 (history expansion)으로 해석됩니다. 항상 값을 **작은따옴표 (single quotes)**로 감싸세요:

# "Sheet1"에서 A1:C10 셀 읽기
gws sheets spreadsheets values get \
--params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1:C10"}'
...

일부 서비스는 자동 생성된 디스커버리 (Discovery) 인터페이스와 함께 수동으로 제작된 헬퍼 명령어 (helper commands)를 제공합니다. 헬퍼 명령어는 + 접두사가 붙어 있어 시각적으로 구분되며, 디스커버리에서 생성된 메서드 이름과 충돌하지 않습니다.

시간 인식형 헬퍼 (+agenda, +standup-report, +weekly-digest, +meeting-prep)는 사용자의 **Google 계정 시간대 (timezone)**를 자동으로 사용합니다 (Calendar Settings API에서 가져오며 24시간 동안 캐싱됨). +agenda에서 --timezone / --tz를 사용하여 재정의하거나, 명시적인 제어를 위해 --timezone 플래그를 설정할 수 있습니다.

Discovery (탐색) 방법과 헬퍼 명령 (helper commands)을 함께 확인하려면 gws <service> --help를 실행하세요.

gws gmail --help # +send, +reply, +reply-all, +forward, +triage, +watch … 등을 표시합니다
gws calendar --help # +insert, +agenda … 등을 표시합니다
gws drive --help # +upload … 등을 표시합니다

전체 헬퍼 참조 (Full helper reference):

서비스 (Service)	명령 (Command)	설명 (Description)
gmail	+send	이메일 전송
gmail	+reply	메시지에 답장 (스레딩을 자동으로 처리)
gmail	+reply-all	메시지에 전체 답장
gmail	+forward	메시지를 새로운 수신자에게 전달
gmail	+triage	읽지 않은 편지함 요약 표시 (발신자, 제목, 날짜)
gmail	+watch	새 이메일을 감시하고 NDJSON 형식으로 스트리밍
sheets	+append	스프레드시트에 행 추가
sheets	+read	스프레드시트에서 값 읽기
docs	+write	문서에 텍스트 추가
chat	+send	스페이스(space)에 메시지 전송
drive	+upload	자동 메타데이터와 함께 파일 업로드
calendar	+insert	새로운 일정 생성
calendar	+agenda	예정된 일정 표시 (Google 계정 시간대 사용; --timezone으로 재정의 가능)
script	+push	Apps Script 프로젝트의 모든 파일을 로컬 파일로 교체
workflow	+standup-report	스탠드업 요약으로서 오늘의 회의 + 미결 작업 표시
workflow	+meeting-prep	다음 회의 준비: 의제, 참석자 및 연결된 문서
workflow	+email-to-task	Gmail 메시지를 Google Tasks 항목으로 변환
workflow	+weekly-digest	주간 요약: 이번 주 회의 + 읽지 않은 이메일 수
workflow	+file-announce	Chat 스페이스에 Drive 파일 공지
events
events	+renew	Workspace Events 구독 갱신/재활성화
modelarmor	+sanitize-prompt	Model Armor 템플릿을 통해 사용자 프롬프트 정화 (Sanitize)
modelarmor	+sanitize-response	Model Armor 템플릿을 통해 모델 응답 정화 (Sanitize)
modelarmor	+create-template	새로운 Model Armor 템플릿 생성

예시 (Examples):

# 이메일 전송
gws gmail +send --to alice@example.com --subject "Hello" --body "Hi there"
# 메시지에 답장
...

Google Cloud Model Armor를 통합하여 API 응답이 에이전트(Agent)에 도달하기 전에 프롬프트 인젝션 (Prompt Injection)을 스캔하세요.

gws gmail users messages get --params '...' \
--sanitize "projects/P/locations/L/templates/T"

변수 (Variable)	설명 (Description)
GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE	기본 Model Armor 템플릿
GOOGLE_WORKSPACE_CLI_SANITIZE_MODE	warn (기본값) 또는 block

모든 변수는 선택 사항입니다. 복사하여 붙여넣을 수 있는 템플릿은 .env.example을 참조하세요.

변수 (Variable)	설명 (Description)
GOOGLE_WORKSPACE_CLI_TOKEN	미리 획득한 OAuth2 액세스 토큰 (최우선 순위)
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE	OAuth 자격 증명 JSON 경로 (사용자 또는 서비스 계정)
GOOGLE_WORKSPACE_CLI_CLIENT_ID	OAuth 클라이언트 ID (client_secret.json 의 대안)
GOOGLE_WORKSPACE_CLI_CLIENT_SECRET	OAuth 클라이언트 비밀번호 (CLIENT_ID 와 쌍을 이룸)
GOOGLE_WORKSPACE_CLI_CONFIG_DIR	설정 디렉토리 재정의 (기본값: ~/.config/gws)
GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE	기본 Model Armor 템플릿
GOOGLE_WORKSPACE_CLI_SANITIZE_MODE	warn (기본값) 또는 block
GOOGLE_WORKSPACE_CLI_LOG	stderr를 위한 로그 레벨 (예: gws=debug). 기본적으로 꺼져 있음.
GOOGLE_WORKSPACE_CLI_LOG_FILE	일일 로테이션이 적용되는 JSON 로그 파일 디렉토리. 기본적으로 꺼져 있음.
GOOGLE_WORKSPACE_PROJECT_ID	할당량/결제(Quota/Billing)를 위한 GCP 프로젝트 ID 재정의 및 헬퍼 명령어를 위한 폴백(Fallback)

환경 변수는 .env 파일(dotenvy를 통해 로드됨)에서도 설정할 수 있습니다.

gws는 구조화된 종료 코드 (Structured exit codes)를 사용하여 스크립트가 에러 출력을 파싱하지 않고도 실패 유형에 따라 분기할 수 있도록 합니다.

코드	의미	예시 원인
0	성공 (Success)	명령이 정상적으로 완료됨
1	API 에러 (API error)	Google에서 4xx/5xx 응답을 반환함
2	인증 에러 (Auth error)	자격 증명(Credentials) 누락, 만료 또는 유효하지 않음
3	유효성 검사 에러 (Validation error)	잘못된 인자(Arguments), 알 수 없는 서비스, 유효하지 않은 플래그
4	디스커버리 에러 (Discovery error)	API 스키마 문서(API schema document)를 가져올 수 없음
5	내부 에러 (Internal error)	예기치 않은 실패

gws drive files list --params '{"fileId": "bad"}'
echo $? # 1 — API error
gws unknown-service files list
...

gws는 2단계 파싱 (two-phase parsing) 전략을 사용합니다:

• argv[1]을 읽어 서비스(예: drive)를 식별합니다. - 해당 서비스의 디스커버리 문서 (Discovery Document, 24시간 캐싱됨)를 가져옵니다.
• 문서의 리소스(Resources)와 메서드(Methods)로부터 clap::Command 트리를 구축합니다. - 남은 인자들을 다시 파싱(Re-parse)합니다.
• 인증(Authenticate)하고, HTTP 요청을 생성하여 실행합니다.

모든 출력 — 성공, 에러, 다운로드 메타데이터 — 은 구조화된 JSON (Structured JSON) 형식입니다.