Google Workspace CLI

Google Workspace CLI (gws): 모든 워크스페이스 API를 위한 통합 솔루션

Google Workspace CLI(일명 gws)는 구글 드라이브(Drive), 지메일(Gmail), 캘린더(Calendar), 시트(Sheets) 등 Google Workspace의 모든 API를 하나의 도구로 제어할 수 있게 해주는 강력한 명령줄 인터페이스입니다. gws는 인간 사용자와 AI 에이전트 모두를 위해 설계되었으며, 복잡한 보일러플레이트 코드 없이 즉각적인 자동화를 가능하게 합니다.

What's gws?

gws는 단순히 정해진 명령어를 실행하는 도구가 아닙니다. 이 도구는 실행 시점에 Google의 Discovery Service를 직접 읽어 들여 전체 명령 표면을 동적으로 구축합니다. 따라서 Google Workspace에 새로운 API 엔드포인트나 메서드가 추가되면 gws는 이를 자동으로 인식하여 사용자에게 제공합니다.

주요 특징은 다음과 같습니다:

• 유연성: 모든 Google Workspace API를 지원합니다.
• 데이터 친화성: 모든 응답을 구조화된 JSON으로 출력하여 후속 처리가 용이합니다.
• 지능형 설계: 40개 이상의 AI 에이전트 기술(Agent Skills)이 포함되어 있어 LLM과의 연동이 매끄럽습니다.

참고: 이 프로젝트는 Google에서 공식적으로 지원하는 제품이 아니며, 현재 활발히 개발 중인 단계입니다.

Features

1. 동적 API 빌드

gws는 고정된 명령 목록을 사용하지 않습니다. Google Discovery Service를 통해 실시간으로 API 스키마를 가져오므로 항상 최신 상태를 유지합니다.

2. 사용자 및 AI 에이전트 최적화

• 인간 사용자용: 복잡한 curl 호출 대신 --help를 통해 도움말을 확인하고, --dry-run으로 요청을 미리 볼 수 있으며 자동 페이지네이션을 지원합니다.
• AI 에이전트용: 모든 응답이 JSON 형식이므로 LLM이 별도의 도구 없이도 워크스페이스를 직접 관리할 수 있습니다. Gemini CLI Extension과 연동하여 기능을 확장할 수 있습니다.

3. 강력한 보안 및 인증

• OAuth2 워크플로우를 지원하며, 로컬 데스크톱, CI 환경, 서버 등 다양한 환경에서 인증이 가능합니다.
• 자격 증명은 AES-256-GCM 방식으로 암호화되어 OS 키링에 안전하게 저장됩니다.

4. 헬퍼 커맨드 (Helper Commands)

기본 API 메서드 외에도 사용자 편의를 위한 전용 헬퍼 커맨드(+ 접두사 사용)를 제공합니다.

• 지메일: +send, +reply, +triage 등
• 드라이브: +upload 등
• 캘린더: +agenda, +insert 등
• 워크플로우: +standup-report, +email-to-task 등

How to Use

설치 방법

gws는 npm을 통해 쉽게 설치할 수 있습니다:

nm install -g @googleworkspace/cli

또는 GitHub Releases에서 미리 빌드된 바이너리를 다운로드하거나 Rust(Cargo)를 사용하여 소스에서 직접 빌드할 수 있습니다.

초기 설정 및 인증

1. 인증 설정: gws auth setup 명령어를 통해 Google Cloud 프로젝트 구성을 안내받습니다.
2. 로그인: gws auth login을 실행하여 OAuth 로그인을 완료합니다.

기본 명령어 예시

• 파일 목록 보기: gws drive files list --params '{"pageSize": 10}'
• 스프레드시트 생성: gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
• 이메일 보내기: gws gmail +send --to [email protected] --subject "Hello" --body "Hi there"
• 오늘의 일정 확인: gws calendar +agenda

Use Case

• 자동화 리포트 생성: 매일 아침 +standup-report를 실행하여 오늘의 회의 일정과 열린 작업 목록을 요약합니다.
• 대량 데이터 관리: --page-all 플래그를 사용하여 드라이브의 수많은 파일을 NDJSON 형식으로 스트리밍하고 jq를 통해 분석합니다.
• AI 에이전트 연동: Gemini CLI 에이전트에게 gws 익스텐션을 설치하여 자연어로 구글 워크스페이스를 조작하도록 명령합니다.
• CI/CD 통합: 헤드리스 환경에서 서비스 계정이나 내보낸 자격 증명 파일을 사용하여 워크스페이스 작업을 자동화합니다.

FAQ

Q: 로그인 시 "Access blocked" 또는 403 오류가 발생합니다. A: OAuth 앱이 '테스트 모드'일 때 발생하는 일반적인 문제입니다. Google Cloud Console의 OAuth 동의 화면에서 사용자의 이메일을 '테스트 사용자'로 추가해야 합니다.

Q: gcloud CLI가 반드시 필요한가요? A: gws auth setup을 통한 자동 설정을 위해서는 gcloud가 필요하지만, Google Cloud Console에서 수동으로 OAuth 자격 증명을 생성하여 client_secret.json 파일을 설정하면 gcloud 없이도 사용할 수 있습니다.

Q: 지원되는 노드 버전은 무엇인가요? A: npm 설치를 위해서는 Node.js 18 버전 이상이 필요합니다.

Q: API가 활성화되지 않았다는 오류가 뜹니다. A: 오류 메시지에 포함된 URL을 클릭하여 해당 Google Cloud 프로젝트에서 필요한 API(예: Gmail API)를 '사용 설정'으로 변경하세요.