@googleworkspace/cli

googleworkspace-cli란?

googleworkspace/cli(배포명 @googleworkspace/cli)는 Google Workspace용 명령줄 도구입니다. Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin 등 여러 Workspace API를 단일 CLI로 사용할 수 있습니다.

명령 인터페이스는 고정된 명령 목록을 배포하는 대신 Google의 Discovery Service에서 런타임에 동적으로 생성됩니다. 프로젝트는 “AI agent skills”를 포함하며, CLI는 자동화를 위한 구조화된 JSON 출력을 강조합니다.

주요 기능

• 여러 Workspace 서비스를 위한 단일 CLI: Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin 및 기타 Workspace API와 상호 작용하는 단일 인터페이스를 제공합니다.
• Discovery Service 기반 동적 명령 생성: 런타임에 Google의 Discovery Service를 읽어 명령과 메서드를 생성하므로, 정적 명령 목록 없이 새로운 엔드포인트/메서드를 자동 수신합니다.
• 구조화된 JSON 출력: 자동화 및 AI 에이전트 사용을 위해 설계되었으며, 응답을 구조화된 JSON으로 반환합니다.
• API 메서드 스키마 검사: gws schema <...>를 사용해 메서드의 요청/응답 스키마를 확인합니다.
• 요청 시뮬레이션 및 페이지네이션 도우미: --dry-run으로 요청 미리보기, --page-all로 페이지네이션 결과 스트리밍(jq 같은 도구로 옵션).
• 다양한 인증 워크플로: 로컬, CI, 서버에 적합한 설정/로그인 워크플로 지원. 사용 가능 시 gcloud 통합 포함.
• 번들된 에이전트 스킬: 저장소 문서에 “40+ agent skills” 포함으로 명시.

googleworkspace-cli 사용 방법

1. CLI 설치:
   • npm으로: npm install -g @googleworkspace/cli
   • GitHub Releases의 사전 빌드 바이너리 사용
   • 소스 빌드: cargo install --git https://github.com/googleworkspace/cli --locked
   • (macOS/Linux은 Homebrew; Nix flake 사용 가능.)
2. 인증 (프로젝트 초기 설정 후 로그인):
   • gws auth setup (gcloud 설치 및 인증 필요)
   • gws auth login (이후 OAuth 로그인)
   • 수동 토큰/콘솔 기반 흐름은 환경 변수 및 수동 OAuth 설정 경로로 문서화.
3. 리소스에 명령 실행. 문서 예시 워크플로:
   • 파일 목록: gws drive files list --params '{"pageSize": 5}'
   • 스프레드시트 생성: gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
   • Chat 메시지 전송: gws chat spaces messages create --params '{"parent": "spaces/xyz"}' --json '{"text": "Deploy complete."}'
   • 스키마 검사: gws schema drive.files.list

사용 사례

• 페이지네이션과 JSON으로 Drive 워크플로 자동화: Drive 목록 엔드포인트에서 대량 결과 스트리밍 후 다운스트림 도구(--page-all 출력과 jq 조합 등)로 처리.
• Gmail/Chat/Calendar 요청을 원시 REST 호출 없이 전송: 생성된 리소스 중심 명령으로 객체 생성/업데이트.
• 실행 전 요청 구조 검증: --dry-run으로 CLI가 보낼 내용을 미리 확인(Sheets, Chat 등 페이로드 생성 시 유용).
• Workspace API 중심 AI 에이전트 도구 구축: 구조화된 JSON 응답과 포함된 에이전트 스킬로 LLM 기반 에이전트가 사용자 정의 코드 없이 Workspace 작업 결정.
• CLI에서 API 메서드 호출 방법 탐색: 메서드 존재는 알지만 요청 형태를 모를 때 gws schema <method>로 요청/응답 스키마 검사.

자주 묻는 질문

• googleworkspace-cli는 Google 공식 제품인가요? 아닙니다. 저장소에 “공식 지원 Google 제품 아님”으로 명시.

• 고정된 명령 목록이 있나요? 없습니다. 문서에 정적 명령 목록을 배포하지 않고, 런타임에 Google Discovery Service를 읽어 명령 인터페이스를 동적으로 생성한다고 명시.

• 설치 및 실행에 필요한 것은? npm 설치 흐름에 Node.js 18+ 필요. 인증은 OAuth 자격 증명을 위한 Google Cloud 프로젝트와 Workspace 액세스 Google 계정 필요.

• 어떤 인증 설정을 사용해야 하나요? 문서에 여러 경로 설명:

  • gcloud 설치 및 인증 시 gcloud 보조 설정(gws auth setup)
  • 자동화 불가 시 Google Cloud Console 수동 OAuth 설정
  • 환경 변수로 토큰/수동 자격 증명(문서화됨)

• 개발/테스트 중 스코프 관련 제한이 있나요? 있습니다. 문서에 OAuth 앱이 검증되지 않음(테스트 모드) 시 Google이 동의 범위를 ~25 스코프로 제한하며, 권장 스코프 프리셋(85+ 스코프)은 검증되지 않은 앱에서 실패—특히 @gmail.com 계정에서—고 경고.

대안

• curl 또는 HTTP 클라이언트로 직접 REST API 호출: Workspace 엔드포인트를 직접 호출할 수 있지만, 요청 형식, 페이지네이션, 인증 세부 사항을 직접 관리해야 합니다.
• 특정 Workspace 서비스용 공식 SDK (예: 언어별 Google APIs 라이브러리): 특정 서비스에 대한 타입화된 클라이언트 메서드를 제공하지만, 일반적으로 API별 별도 코드 경로를 가지며 하나의 동적 생성 CLI 인터페이스가 아닙니다.
• Google APIs용 기타 CLI 도구: 대안 CLI는 특정 서비스에 초점을 맞추거나 정적 명령 세트를 사용할 수 있습니다; 도구에 따라 여기에 설명된 동적 Discovery Service 기반 명령 생성이나 구조화된 JSON + 스키마 내省 워크플로를 제공하지 않을 수 있습니다.