원문 보기
GitHub - googleworkspace/cli: Google Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.
Service

GitHub - googleworkspace/cli: Google Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.

googleworkspace
2026.03.07
·GitHub·by 이호민
#AI Agent#Automation#CLI#Google Workspace#Productivity

핵심 포인트

  • 1gws는 Google Workspace API를 위한 CLI 도구로, Google의 Discovery Service에서 명령어를 동적으로 생성하여 사람과 AI 에이전트 모두에게 사용됩니다.
  • 2이 도구는 structured JSON 출력을 제공하고 `--help`, auto-pagination과 같은 기능을 통해 API 상호작용을 간소화하며, 포함된 agent skills로 AI 에이전트 통합을 지원합니다.
  • 3`gws`는 `gcloud`를 이용한 자동 설정부터 service account 및 pre-obtained token에 이르기까지 다양한 authentication 방법을 지원하여 여러 환경에서 유연성을 제공합니다.

gws는 Google Workspace의 모든 API(Drive, Gmail, Calendar 등)에 대한 단일 CLI 도구로, 사람과 AI 에이전트 모두를 위해 설계되었습니다. 이 도구는 curl을 통한 REST API 호출의 필요성을 없애고, 구조화된 JSON 출력을 제공하며, 40개 이상의 에이전트 스킬을 포함합니다.

gws의 핵심 방법론은 Google의 Discovery Service를 런타임에 활용하여 전체 커맨드 표면을 동적으로 구축한다는 점입니다. 이는 Google Workspace가 새로운 API 엔드포인트나 메서드를 추가할 때 gws가 자동으로 이를 인식하고 통합함을 의미합니다. 이 동적 특성은 정적 명령 목록을 사용하는 기존 CLI와 차별화됩니다.

기술적 방법론 상세:

  1. 두 단계 파싱 (Two-phase Parsing):
    • 첫 번째 단계에서 gws는 argv[1]을 읽어 사용할 서비스(예: drive, gmail)를 식별합니다.
    • 해당 서비스의 Discovery Document를 Google API Discovery Service로부터 가져옵니다(24시간 캐싱). 이 문서는 서비스가 제공하는 리소스와 메서드에 대한 모든 메타데이터를 포함합니다.
    • 두 번째 단계에서, Discovery Document의 정보를 사용하여 Rust의 CLI 크레이트인 clap::Command 트리를 동적으로 생성합니다. 이 트리는 해당 서비스의 모든 리소스와 메서드를 나타내며, CLI 명령 구조에 매핑됩니다.
    • 나머지 명령줄 인수를 새로 구축된 clap::Command 트리를 기반으로 다시 파싱합니다.
  2. 실행: 파싱이 완료되면, gws는 적절한 인증을 수행하고, 파싱된 인수를 기반으로 HTTP 요청을 구축한 다음, Google Workspace API를 실행합니다. 모든 출력(성공, 오류, 다운로드 메타데이터)은 구조화된 JSON 형식으로 제공됩니다.

주요 기능 및 사용성:

  • 인간 사용자용: 모든 리소스에 대한 --help 옵션, 요청 미리보기를 위한 --dry-run, 자동 페이지네이션 등의 기능을 제공하여 curl 호출 없이 직관적인 사용을 가능하게 합니다.
  • AI 에이전트용: 모든 응답이 구조화된 JSON이므로 LLM이 사용자 지정 도구 없이 Workspace를 관리할 수 있도록 합니다. 100개 이상의 SKILL.md 파일 형태로 제공되는 에이전트 스킬을 통해 Gmail, Drive, Docs, Calendar, Sheets에 대한 고수준의 작업 및 레시피를 지원합니다. 이 스킬들은 npx skills add 명령어로 설치할 수 있으며, OpenClaw 및 Gemini CLI와 같은 에이전트 프레임워크와 연동됩니다.
  • 인증 (Authentication):
    • 다양한 인증 워크플로우를 지원합니다: gws auth setup을 통한 대화형 OAuth 설정 (로컬 데스크톱에 암호화된 자격 증명 저장), 수동 OAuth 설정, 헤드리스/CI 환경을 위한 자격 증명 내보내기, 서비스 계정, 사전 획득된 액세스 토큰 사용 등입니다.
    • gws auth setup은 gcloud CLI를 사용하여 Google Cloud 프로젝트 설정 및 API 활성화를 자동화합니다.
    • 환경 변수 (GOOGLE_WORKSPACE_CLI_TOKEN, GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE 등) 및 .env 파일을 통한 자격 증명 관리가 가능하며, 우선순위가 정의되어 있습니다.
  • 고급 사용:
    • 다중 파트 업로드 (Multipart Uploads): gws drive files create --upload와 같이 파일을 업로드할 수 있습니다.
    • 페이지네이션 (Pagination): --page-all 플래그를 사용하여 모든 페이지를 NDJSON 형식으로 스트리밍하고, --page-limit 및 --page-delay로 동작을 제어할 수 있습니다.
    • Shell Escaping: Google Sheets의 범위 (Sheet1!A1)와 같이 특수 문자가 포함된 인수는 셸 확장 문제를 피하기 위해 항상 작은따옴표로 감싸야 합니다.
    • 모델 아머 (Model Armor): --sanitize 플래그를 통해 Google Cloud Model Armor를 통합하여 API 응답에서 프롬프트 인젝션 위험을 스캔할 수 있습니다. GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE 및 GOOGLE_WORKSPACE_CLI_SANITIZE_MODE (warn 또는 block) 환경 변수로 설정을 제어합니다.

문제 해결:
일반적인 문제로는 OAuth 앱의 "Access blocked" 또는 "Google hasn't verified this app" (테스트 사용자 추가 및 계속 진행 필요), 스코프 제한 초과 (필요한 스코프만 선택), gcloud CLI 누락, redirect_uri_mismatch (OAuth 클라이언트 유형 오류), API 미활성화 (accessNotConfigured 오류 및 활성화 URL 제공) 등이 있으며, 각 문제에 대한 명확한 해결책이 제시되어 있습니다.

이 프로젝트는 현재 활발히 개발 중이며, v1.0을 향한 과정에서 Breaking Changes가 예상될 수 있습니다. 비공식 Google 제품입니다.