Blog

Google Workspace CLI 활용법 및 사용법

Herve Kom

Herve Kom

17 March 2026

Google Workspace CLI 활용법 및 사용법

Google Workspace CLI 소개

Google Workspace CLI(gws로 호출)는 인간과 AI 에이전트에게 Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin 및 모든 Google Workspace API에 통합된 액세스를 제공하는 오픈 소스 동적 명령줄 도구입니다. 이 도구는 Google의 라이브 Discovery Service를 기반으로 직접 구축되어 업데이트 없이도 명령이 최신 상태를 유지합니다. npm을 통해 Google Workspace CLI를 전역으로 설치하고, OAuth로 한 번 인증한 다음, 포함된 스킬을 사용하여 Claude Code 또는 Cursor와 같은 에이전트에 연결하세요. 상용구 OAuth 흐름이나 별도의 SDK가 필요하지 않습니다.

Google Workspace CLI란 무엇이며 왜 중요한가요?모든 개발자, 관리자 및 AI 에이전트 사용자가 겪는 문제는 다음과 같습니다. Google Workspace 서비스(Drive 파일, Gmail 전송, Calendar 이벤트 생성, Sheets에 추가, Docs 편집, Chat에 게시)를 자동화하거나 쿼리하고 싶지만, 결국 사용자 지정 curl 스크립트를 작성하거나, OAuth 범위와 씨름하거나, 수동으로 페이지 매김을 처리하거나, 구식이 되는 여러 SDK를 한데 묶게 됩니다.

이러한 문제는 Google의 Workspace API가 강력하지만 파편화되어 있기 때문에 발생합니다. 각 서비스마다 고유한 엔드포인트, 인증 흐름 및 특성이 있습니다. 기존 도구는 API 변경 시 중단되는 상용구 코드를 유지 관리하도록 강요합니다.

Google Workspace CLI는 이 문제를 해결합니다. Google 팀이 2026년 초에 출시한(Addy Osmani가 발표) 이 도구는 Google의 Discovery Service를 사용하여 런타임에 모든 Workspace API 메서드를 동적으로 검색하는 단일 Rust 기반 CLI입니다. 도구 업데이트를 기다리지 않고도 새로운 엔드포인트에 즉시 액세스할 수 있습니다.

그 결과, 스크립트, 에이전트 및 일상적인 터미널 작업이 정확하고 최신 상태를 유지합니다. Google Workspace CLI는 깔끔한 JSON을 출력하고, 드라이 런(dry-run), 페이지 매김 도우미를 지원하며, gws gmail +send 또는 gws calendar +agenda와 같은 40개 이상의 사용자 친화적인 단축키(+ 접두사)를 포함합니다.

Google Workspace CLI는 또한 즉시 설치 가능한 에이전트 스킬과 함께 제공되므로 Claude Code, Cursor, OpenClaw 또는 Gemini CLI와 같은 도구가 사용자 지정 도구 정의 없이 Workspace를 자율적으로 관리할 수 있습니다.

Workspace 자동화와 함께 API 통합을 구축하거나 테스트하는 경우, Apidog가 검증을 담당합니다. Apidog는 요청 전송, 응답 검사, 환경 관리 및 테스트 스위트 실행을 위한 무료 API 클라이언트입니다. Google Workspace CLI는 데이터에 대한 실시간 액세스를 제공하며, Apidog는 모든 호출이 예상대로 작동하는지 확인합니다.

Google Workspace CLI 설치유일한 요구 사항은 Node.js 18 이상입니다. 다음 명령으로 버전을 확인하세요:

node --version

설치 없이 실행Google Workspace CLI를 가장 빠르게 시도하는 방법은 npx를 사용하는 것입니다(매번 최신 버전을 가져옵니다):

npx @googleworkspace/cli --help
npx @googleworkspace/cli drive files list --params '{"pageSize":1}'

빠른 테스트나 일회성 스크립트에 적합합니다.

전역으로 설치정기적으로 사용하려면 gws 명령을 항상 사용할 수 있도록 전역으로 설치하세요:

npm install -g @googleworkspace/cli gws --version

Google Workspace CLI는 미리 빌드된 바이너리를 번들로 제공하므로 시작이 빠르며 로컬에서 Rust를 컴파일할 필요가 없습니다. GitHub Releases에서 바이너리를 가져오거나, Homebrew(brew install googleworkspace/cli)를 사용하거나, 선호하는 경우 Nix를 통해 실행할 수도 있습니다.

AI 코딩 에이전트를 위한 Google Workspace CLI 설정gws auth setup 명령은 하나의 안내 흐름으로 프로젝트 생성, API 활성화 및 초기 OAuth를 처리합니다. 다음을 실행하세요:

gws auth setup

그러면 브라우저가 열리고, 필요한 경우 Google Cloud 프로젝트를 생성하고, 필요한 API를 활성화하며, 자격 증명을 OS 키체인에 안전하게 저장합니다(AES-256-GCM 암호화).

특정 에이전트 대상 지정 또는 스킬 설치설정 후 번들로 제공되는 에이전트 스킬을 설치하세요:

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

또는 에이전트별 설치 프로그램(예: Claude Code 또는 Cursor용)을 실행하세요. 에이전트를 다시 시작하여 Google Workspace CLI 명령을 자동으로 검색하도록 하세요.

프로젝트 수준 vs. 전역 설정기본적으로 설정은 전역으로 적용됩니다. 프로젝트 전용 구성의 경우:

gws auth setup --project

인증언제든지 다시 인증하거나 계정을 전환하세요:

gws auth login

현재 사용자 및 범위를 확인하세요:

gws auth whoami

필요할 때 로그아웃하세요:

gws auth logout

헤드리스/CI 사용의 경우, 자격 증명을 내보내세요:

gws auth export --unmasked > creds.json
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/creds.json

또는 gcloud 토큰을 재사용하세요: export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token).

원격 측정 (Telemetry)익명 사용량 수집을 비활성화하세요:

export GOOGLE_WORKSPACE_CLI_NO_TELEMETRY=1

Google Workspace CLI에서 핵심 명령 사용하기 (Drive, Gmail, Calendar, Sheets, Docs, Chat)Google Workspace CLI는 명령을 동적으로 검색하므로 고정된 목록이 없습니다. gws --help를 실행하여 사용 가능한 서비스를 확인하세요.

Drive 파일 및 폴더최근 파일 목록을 보려면:

gws drive files list --params '{"pageSize":10, "q":"name contains report"}'

도우미로 업로드:

gws drive +upload ./budget.xlsx --name "2026 Budget"

Gmail이메일 보내기:

gws gmail +send --to colleague@example.com --subject "Update" --body "See attached." --attach ./file.pdf

답장 또는 받은 편지함 분류:

gws gmail +reply --message-id <ID> --body "Thanks!"
gws gmail +triage

Calendar이벤트 생성:

gws calendar +insert --summary "Sprint Planning" --start "2026-03-20T10:00" --end "2026-03-20T11:00" --attendees "team@example.com"

오늘 일정 표시:

gws calendar +agenda --today

Sheets행 추가:

gws sheets +append --spreadsheetId <ID> --range "Sheet1!A:C" --values "Task X,Done,2026-03-16"

Docs텍스트 삽입:

gws docs +write --documentId <ID> --text "New section added via Google Workspace CLI"

Chat메시지 게시:

gws chat +send --space <SPACE_ID> --text "Deployment complete 🚀"

어떤 명령에서든 --dry-run을 사용하여 실행 없이 정확한 API 호출을 미리 볼 수 있습니다. NDJSON으로 전체 페이지 매김을 위해 --page-all을 추가하세요.

Google Workspace CLI의 고급 구성 및 전역 옵션환경 변수 또는 .env 파일로 설정 유지:

export GOOGLE_WORKSPACE_CLI_DEFAULT_PARAMS='{"prettyPrint":true}'

타임아웃, 출력 형식(--json, --yaml)을 조정하거나 파일 기반 키체인을 강제할 수 있습니다. 구성 보기:

gws config

Google Workspace CLI를 AI 에이전트 및 프롬프트와 통합하기스킬이 설치되면 에이전트는 Google Workspace CLI를 기본적으로 호출합니다.

"use gws" 패턴프롬프트에서: "Google Workspace CLI를 사용하여 최근 Drive 파일 목록을 표시" 또는 "Google Workspace CLI를 통해 후속 이메일 전송".

자동 호출 규칙에이전트 지침(예: CLAUDE.md 또는 Cursor 규칙)에 추가:

"작업에 Gmail, Drive, Calendar, Sheets, Docs 또는 Chat이 포함될 때마다 응답하기 전에 Google Workspace CLI 명령을 자동으로 사용하십시오. 먼저 서비스와 메서드를 결정하십시오."

에이전트는 파일 경로 또는 JSON 결과를 반환하여 컨텍스트를 간결하게 유지합니다.

Apidog와 함께 사용하여 완벽한 API 신뢰 얻기Google Workspace CLI는 Workspace API에 즉시 액세스할 수 있도록 하지만, 페이로드, 범위 또는 응답을 디버깅할 때 가시성이 필요합니다.

Apidog는 요청을 보내고, 원시 응답을 검사하고, OAuth 토큰으로 환경을 설정하고, 어설션을 자동화할 수 있는 무료 API 클라이언트입니다.

실제 워크플로:

Google Workspace CLI + Apidog는 실시간 데이터 액세스 및 검증된 반복 가능한 API 테스트를 제공합니다.

자주 묻는 질문Google Workspace CLI가 내 데이터를 외부로 전송합니까?Google API로 직접적인 호출은 이루어지지 않습니다. 귀하의 콘텐츠는 Google 계정을 벗어나지 않습니다.

Google Workspace CLI는 어떤 서비스를 지원합니까?Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, Script 등 동적으로 검색되는 모든 Workspace API를 지원합니다.

명령은 얼마나 최신 상태입니까?Google Workspace CLI는 라이브 Discovery Service를 쿼리하므로 새로운 메서드가 자동으로 나타납니다.

API 키가 필요합니까?표준 Google OAuth 또는 서비스 계정을 사용하며, 인증 자격 증명 외에 별도의 키는 필요하지 않습니다.

Google Workspace CLI는 어떤 에이전트 및 편집기를 지원합니까?Claude Code, Cursor, OpenClaw, Gemini CLI, VS Code 확장 프로그램 등 모든 MCP 또는 Agent Skills 호환 도구를 지원합니다.

원시 명령과 + 도우미의 차이점은 무엇입니까?원시 명령은 정확한 Discovery 메서드(예: drive.files.list)입니다. + 도우미는 일반적인 작업(예: +upload, +send)을 위한 단축키입니다.

AI 에이전트 없이 Google Workspace CLI를 사용할 수 있습니까?예, 스크립트, 자동화 또는 일상적인 터미널 사용에 완벽합니다.button

추가 자료

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드