gws는 드라이브·지메일·캘린더·시트 같은 구글 워크스페이스를 터미널에서 다루는 CLI다. 다른 CLI와 다른 점은 명령어 목록이 바이너리 안에 들어 있지 않다는 것이다. 실행하는 순간 구글의 Discovery 문서를 읽어서 명령 트리를 새로 만든다. 이 글은 그 구조를 실제로 설치해서 확인한 순서대로 정리한다.
30초 요약
| 궁금한 것 | 답 |
|---|---|
| 무엇인가 | 구글 워크스페이스 18개 서비스를 한 바이너리로 다루는 CLI (README) |
| 핵심 구조 | 명령어를 하드코딩하지 않고 실행할 때 Discovery 문서를 받아 명령 트리를 만든다(2단계 파싱) |
| 실측값 | Drive v3 Discovery 기준 리소스 14개·메서드 64개, 캐시 파일 263KB(~/.config/gws/cache/drive_v3.json) |
| 명령 두 종류 | Discovery가 만든 명령 + 손으로 만든 + 헬퍼(+send, +agenda, +standup-report) |
| 인증 순서 | 토큰 env → 자격증명 파일 env → gws auth login(AES-256-GCM + OS 키체인) → 평문 파일 |
| 출력 | 전부 JSON. --format table/yaml/csv, --page-all은 페이지마다 한 줄(NDJSON) |
| 종료 코드 | 0 성공 · 1 API 오류 · 2 인증 오류 · 3 검증 오류 · 4 Discovery 오류 · 5 내부 오류 |
| 내가 받은 버전 | v0.22.5 (2026-03-31 공개) — gws 0.22.5 |
| 주의 | 저장소에 "not an officially supported Google product"라고 적혀 있다. 구글 공식 지원 제품이 아니다 |

그림 1. gws의 구조. 실행 시 Discovery 문서를 받아 명령 트리를 만들고, 인증을 거쳐 HTTP 요청으로 나간다.
목차
- gws CLI란 — 설치부터 첫 실행까지
- 핵심 구조 — Discovery 문서로 명령 트리를 만든다
- 실제 명령 계층 — drive 하나에 리소스 14개, 메서드 64개
- 두 종류의 명령 — Discovery 메서드와
+헬퍼 - 인증 구조 — 우선순위 4단계와 키체인 암호화
- 출력과 종료 코드 — 스크립트가 분기할 수 있게
- 에이전트 스킬 레이어 — SKILL.md 100개
- 내가 막혔던 곳
- 참고 자료
gws CLI란 — 설치부터 첫 실행까지
한 줄로 말하면 "구글 워크스페이스 REST API를 사람이 쓰기 좋은 명령어로 감싼 래퍼"다. 서비스마다 따로 만들어진 CLI가 아니라, 바이너리 하나가 18개 서비스를 전부 담당한다. Rust로 작성돼 있어서 cargo install과 Nix로도 설치할 수 있고, 정적 바이너리라 런타임 의존성이 없다 (README).
설치 경로는 세 가지다.
# 1) 릴리스 바이너리 (권장)
curl -LO https://github.com/googleworkspace/cli/releases/download/v0.22.5/google-workspace-cli-x86_64-apple-darwin.tar.gz
tar xzf google-workspace-cli-x86_64-apple-darwin.tar.gz # gws 바이너리 하나가 나온다
# 2) Homebrew (macOS·Linux)
brew install googleworkspace-cli
# 3) npm — 릴리스 바이너리를 내려받아 주는 래퍼
npm install -g @googleworkspace/cli
설치 후 첫 화면은 이렇게 나온다. 확인 겸 면책 문구까지 같이 찍힌다.
$ ./gws --version
gws 0.22.5
This is not an officially supported Google product.
인증은 두 단계다. gws auth setup은 gcloud로 클라우드 프로젝트 생성·API 활성화·로그인까지 한 번에 처리하고, 그다음부터는 gws auth login만 쓰면 된다. gcloud가 없으면 클라우드 콘솔에서 OAuth 클라이언트(Desktop app)를 만들어 ~/.config/gws/client_secret.json에 두는 수동 경로가 있다.
gws auth setup # 최초 1회: 프로젝트 + API + 로그인
gws auth login # 이후: 스코프 선택과 로그인
gws drive files list --params '{"pageSize": 5}'
첫 실행 뒤 설정 디렉터리가 이렇게 생긴다. 구조를 이해할 때 제일 먼저 봐야 하는 곳이다.
~/.config/gws/
├── cache/drive_v3.json # Discovery 문서 캐시 (24시간 유효)
├── client_secret.json # OAuth 클라이언트 (수동 설정 시)
├── credentials.json # 암호화된 자격증명
└── .encryption_key # KEYRING_BACKEND=file일 때만
핵심 구조 — Discovery 문서로 명령 트리를 만든다
gws의 가장 큰 특징은 명령어 정의가 코드에 없다는 점이다. 저장소 설명에도 "Dynamically built from Google Discovery Service"라고 적혀 있다. 구글이 새 API 메서드를 추가하면 CLI를 업데이트하지 않아도 다음 실행에서 자동으로 그 명령이 생긴다 (Discovery Service).
실행 흐름은 2단계 파싱이다.
argv[1]만 먼저 읽어 서비스 이름을 알아낸다 (drive,gmail같은 값).- 그 서비스의 Discovery 문서를 받아온다. 캐시가 있으면 24시간 동안 재사용한다.
- 문서의 리소스·메서드 정의로
clap명령 트리를 만든다. - 남은 인자를 그 트리로 다시 파싱한다.
- 인증 → HTTP 요청 조립 → 실행 → JSON 출력.
내 환경에서 실제로 확인한 값은 이렇다. 캐시 파일은 263KB였고, 문서 리비전은 20261109였다.
$ ls -lh ~/.config/gws/cache/
-rw------- 263K drive_v3.json
$ gws schema drive.files.list | head -3
{
"description": " Lists the user's files. ...",
"httpMethod": "GET",
여기서 gws schema <service.resource.method>가 중요하다. Discovery 문서를 그대로 보여주는 명령이라, 어떤 파라미터가 필수인지, 응답이 어떤 모양인지 CLI 안에서 바로 확인할 수 있다. 문서 사이트를 따로 열 필요가 없다. --resolve-refs를 붙이면 $ref 참조까지 펼쳐서 보여준다.
2단계 파싱의 대가도 있다. 서비스 이름을 틀리면 3번(검증 오류)으로 끝나고, Discovery 문서를 못 받으면 4번(Discovery 오류)으로 끝난다. 둘 다 "명령이 틀렸다"가 아니라 "명령 트리를 못 만들었다"는 뜻이라 원인을 구분해서 봐야 한다.
실제 명령 계층 — drive 하나에 리소스 14개, 메서드 64개
gws drive --help를 치면 Discovery 문서의 리소스가 그대로 하위 명령으로 나열된다.
$ gws drive --help
The Google Drive API allows clients to access resources from Google Drive.
Commands:
+upload [Helper] Upload a file with automatic metadata
about Operations on the 'about' resource
accessproposals Operations on the 'accessproposals' resource
apps Operations on the 'apps' resource
changes Operations on the 'changes' resource
channels Operations on the 'channels' resource
comments Operations on the 'comments' resource
drives Operations on the 'drives' resource
files Operations on the 'files' resource
permissions Operations on the 'permissions' resource
...

그림 3. 실제 실행 출력. 리소스 목록이 곧 Discovery 문서의 리소스 목록이다.
명령은 gws <service> <resource> [sub-resource] <method> 순서로 내려간다. REST 경로를 거의 그대로 옮긴 형태라, API 문서를 읽을 줄 알면 CLI 사용법은 절반쯤 안 것이다.
| REST 요청 | gws 명령 |
|---|---|
GET /drive/v3/files | gws drive files list --params '{"pageSize":10}' |
GET /drive/v3/files/{fileId} | gws drive files get --params '{"fileId":"abc123"}' |
POST /gmail/v1/users/me/messages/send | gws gmail users messages send --json '{"raw":"..."}' |
GET /sheets/v4/spreadsheets/{id}/values/{range} | gws sheets spreadsheets values get --params '{...}' |
POST /upload/drive/v3/files | gws drive files create --json '{...}' --upload ./report.pdf |
리소스가 3단으로 내려가는 서비스도 있다. 지메일은 users → messages → attachments처럼 하위 리소스가 붙는다. 그래서 명령이 gws gmail users messages attachments get까지 길어진다. 계층을 외우는 게 아니라 --help를 따라 내려가면 된다.
전역 플래그는 서비스 공통이라 표로 정리해 두면 편하다.
| 플래그 | 하는 일 | |||
|---|---|---|---|---|
--params <JSON> | URL·쿼리 파라미터 | |||
--json <JSON> | 요청 본문(POST·PATCH·PUT) | |||
--upload <PATH> | 파일을 multipart로 업로드 | |||
--dry-run | 요청만 조립하고 전송하지 않음 | |||
| `--format json\ | table\ | yaml\ | csv` | 출력 형식 |
--page-all | 자동 페이지네이션, 페이지마다 JSON 한 줄 | |||
| `--api-version v2\ | v3` | API 버전 강제 |
두 종류의 명령 — Discovery 메서드와 + 헬퍼
자동 생성 명령만으로는 "안 읽은 메일 요약" 같은 일상 작업이 너무 번거롭다. 그래서 저장소가 손으로 만든 헬퍼를 따로 넣어 두는데, 자동 생성 이름과 절대 겹치지 않도록 앞에 +를 붙인다. --help에서도 [Helper]로 구분해 보여준다.
$ gws workflow --help
Commands:
+standup-report [Helper] Today's meetings + open tasks as a standup summary
+meeting-prep [Helper] Prepare for your next meeting: agenda, attendees, and linked docs
+email-to-task [Helper] Convert a Gmail message into a Google Tasks entry
+weekly-digest [Helper] Weekly summary: this week's meetings + unread email count
+file-announce [Helper] Announce a Drive file in a Chat space
| 서비스 | 헬퍼 | 하는 일 |
|---|---|---|
| gmail | +send +reply +reply-all +forward | 스레딩까지 알아서 처리하는 메일 명령 |
| gmail | +triage +watch | 안 읽은 메일 요약, 새 메일 NDJSON 스트리밍 |
| calendar | +agenda +insert | 다가오는 일정, 일정 생성 |
| sheets | +read +append | 범위 읽기, 행 추가 |
| drive | +upload | 메타데이터 자동으로 채워 업로드 |
| workflow | +standup-report +meeting-prep +weekly-digest | 여러 서비스를 묶은 요약 |
| modelarmor | +sanitize-prompt +sanitize-response | 프롬프트 인젝션 검사 |
+agenda 같은 시간 인식 헬퍼는 캘린더 설정 API에서 계정 시간대를 읽어 24시간 캐시한다. 시간대를 바꾸려면 --timezone Asia/Seoul처럼 플래그로 덮으면 된다.
인증 구조 — 우선순위 4단계와 키체인 암호화
자격증명은 정해진 순서로 찾는다. 위에서부터 먼저 발견되는 것을 쓴다.
| 순위 | 방식 | 설정 |
|---|---|---|
| 1 | 액세스 토큰 | GOOGLE_WORKSPACE_CLI_TOKEN |
| 2 | 자격증명 파일 | GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE |
| 3 | 암호화된 자격증명 | gws auth login 결과 |
| 4 | 평문 자격증명 | ~/.config/gws/credentials.json |
3번은 저장 방식이 눈에 띈다. 자격증명을 AES-256-GCM으로 암호화하고, 키는 OS 키체인(맥은 Keychain Access, 윈도는 Credential Manager)에 넣는다. 0.22.3에서 키체인 연동이 엄격해져서, 예전처럼 키 파일을 평문으로 떨어뜨리지 않는다. 키 파일을 꼭 써야 하는 환경에서만 GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file로 바꾼다 (CHANGELOG).
서버나 CI에서는 두 가지 방법을 쓴다. 브라우저가 있는 기기에서 자격증명을 내보내 옮기거나, 서비스 계정 키를 그대로 가리킨다.
# 브라우저 있는 기기에서 내보내기 → 헤드리스 서버에서 사용
gws auth export --unmasked > credentials.json
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
# 이미 토큰을 발급하는 도구가 있을 때
export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
주의할 점은 OAuth 앱이 테스트 모드일 때 스코프가 25개로 제한된다는 것이다. 권장 프리셋은 85개가 넘는 스코프를 요청하기 때문에, @gmail.com 계정에서는 그대로 실패한다. 필요한 서비스만 골라서 로그인해야 한다.
gws auth login -s drive,gmail,sheets
출력과 종료 코드 — 스크립트가 분기할 수 있게
성공이든 실패든 출력은 JSON이다. 인증이 없을 때 내가 받은 응답은 이랬다.
{
"error": {
"code": 401,
"message": "Access denied. No credentials provided. Run `gws auth login` or set GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE to an OAuth credentials JSON file.",
"reason": "authError"
}
}
종료 코드도 실패 종류별로 나뉜다. 에러 메시지를 정규식으로 긁지 않아도 스크립트가 분기할 수 있다는 뜻이다.
| 코드 | 의미 | 내가 직접 확인한 경우 |
|---|---|---|
| 0 | 성공 | gws --version, --dry-run |
| 1 | API 오류 | 잘못된 fileId |
| 2 | 인증 오류 | 자격증명 없이 drive files list → 2 |
| 3 | 검증 오류 | gws unknown-service files list → 3 |
| 4 | Discovery 오류 | Discovery 문서를 못 받음 |
| 5 | 내부 오류 | 예기치 않은 실패 |
--dry-run은 인증을 건너뛰고 요청 조립 결과만 보여준다. API를 호출하기 전에 URL과 multipart 여부를 확인하기 좋다.
$ gws gmail +send --to a@b.com --subject t --body hi --dry-run
{
"body": null,
"dry_run": true,
"is_multipart_upload": true,
"method": "POST",
"query_params": [],
"url": "https://gmail.googleapis.com/upload/gmail/v1/users/me/messages/send"
}
목록 API는 --page-all로 자동 페이지네이션을 켠다. 결과가 페이지마다 JSON 한 줄(NDJSON)로 떨어지므로 jq로 바로 이어 붙이면 된다.
gws drive files list --params '{"pageSize":100}' --page-all --page-limit 5 \
| jq -r '.files[].name'

그림 2. 자동 생성 명령과 + 헬퍼, 그리고 인증·출력 계층이 겹쳐 있는 구조.
에이전트 스킬 레이어 — SKILL.md 100개
저장소가 CLI만 배포하지 않는다는 점도 구조의 일부다. 서비스마다 SKILL.md를 두고, 헬퍼와 자주 쓰는 레시피까지 문서로 묶어서 같이 배포한다. README 기준 100개가 넘고, 목록은 gws generate-skills로 자동 생성된다 (Skills Index).
# 전체 스킬 설치
npx skills add https://github.com/googleworkspace/cli
# 필요한 것만
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
# OpenClaw에서 저장소와 동기화된 상태로 쓰기
ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/
이 구조가 에이전트에 잘 맞는 이유는 두 가지다. 모든 응답이 JSON이라 파싱 규칙이 하나면 되고, --sanitize로 Model Armor를 걸면 API 응답을 에이전트에 넣기 전에 프롬프트 인젝션을 검사할 수 있다.
gws gmail users messages get --params '...' \
--sanitize "projects/P/locations/L/templates/T"
Gemini CLI 확장으로도 붙는다. 이 경우 gws가 자기 인증을 직접 관리하므로 터미널에서 한 번만 로그인하면 확장이 그 자격증명을 이어받는다.
내가 막혔던 곳
처음 npm install @googleworkspace/cli로 설치했더니 바이너리가 없었다. 이 npm 설정이 postinstall 스크립트를 자동 실행하지 않아서(allow-scripts 경고만 뜨고 스킵) 바이너리 다운로드 단계가 건너뛰어진 탓이다. 결국 릴리스 tar.gz를 직접 받아 풀었다. 0.22.5 체인지로그에 "바이너리가 없으면 실행 시 자동 설치" 수정이 들어간 걸 보면 같은 일을 겪은 사람이 나뿐은 아닌 것 같다.
두 번째는 따옴표다. --params는 JSON 문자열이라 반드시 작은따옴표로 감싸야 한다. 큰따옴표로 감싸면 셸이 먼저 해석해서 JSON이 깨지고, 시트 범위의 !는 zsh 히스토리 확장으로 먹혀 버린다. '{"range": "Sheet1!A1:C10"}'처럼 통째로 감싸는 게 안전하다.
세 번째는 종료 코드다. gws ... | head로 출력을 자르고 echo $?를 찍었더니 0이 나왔다. 파이프의 마지막 명령(head) 상태가 찍힌 것이라 gws의 실패가 가려진 것이다. 지금은 출력을 파일로 돌리고 ; echo $?를 따로 찍어서 확인한다.
참고 자료
- googleworkspace/cli — 설치·인증·아키텍처·종료 코드 원문
- Releases (v0.22.5) — OS별 바이너리와 체크섬
- Google Discovery Service — CLI가 명령 트리를 만드는 근거 문서
- Skills Index — 서비스·헬퍼 스킬 전체 목록
- @googleworkspace/cli (npm) — npm 설치 경로
- Claude Code 설치·사용법 — 터미널에서 쓰는 AI CLI 비교용
- Mac 개발환경 세팅 — Homebrew로 CLI 설치하는 기본기
- Claude API 사용법 (Python) — REST API를 직접 호출하는 방식과 비교
'IT' 카테고리의 다른 글
| 코딩테스트 Python 준비 — 3개월 로드맵과 필수 문법·자료구조 (0) | 2026.11.17 |
|---|---|
| 개발자 AI 공부 순서 — API 호출부터 에이전트까지 8주 로드맵 (0) | 2026.11.16 |
| crontab 사용법 — 5필드 읽는 법과 "안 돌 때" 확인 순서 (0) | 2026.11.16 |
| Docker 입문 사용법 — 설치부터 이미지·컨테이너 구분까지 (0) | 2026.11.15 |
| Opus 5.5 effort 추천 — claude.dev가 밝힌 기본값 medium 총정리 (2026) (0) | 2026.11.14 |















