GWS CLI 사용법 설치부터 구글 워크스페이스 연동까지 총정리

Google Workspace 업무를 자동화하려면 서비스별 API와 SDK를 확인하거나 Apps Script를 따로 작성해야하는 불편함을 터미널 환경에서 연동해 해결하는 도구가 오픈 소스로 개발되었습니다. 바로 ‘GWS CLI’입니다. 

Google API 구조를 명령어로 바꾸고 결과를 JSON으로 제공해, 셸 스크립트와 AI 에이전트에서도 활용하기 쉽게 만든 것이 특징입니다.

이 글에서는 GWS CLI가 무엇인지, 왜 AI 에이전트 도구로 주목받고 있는지 살펴보겠습니다. 설치와 인증 방법부터 주요 명령어, Gemini CLI 연동, 실무 활용법과 도입 전 확인해야 할 한계까지 함께 정리해보겠습니다.

GWS CLI 핵심 요약

• Google Workspace 서비스를 하나의 CLI로 제어합니다. Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin 등 여러 Workspace API를 gws 명령어로 호출할 수 있습니다.
• Google Discovery Service를 기반으로 명령어를 구성합니다. 미리 정해진 명령어 목록만 사용하는 것이 아니라, Google의 API 문서를 읽어 실행 가능한 명령 구조를 동적으로 만듭니다.
• 모든 결과를 JSON 형태로 반환합니다. 결과를 jq나 셸 스크립트로 가공할 수 있으며, 구조화된 데이터를 처리하는 AI 에이전트와도 연결하기 좋습니다.
• 반복 업무를 위한 Helper Command를 제공합니다. 메일 분류, 일정 확인, 파일 업로드, 회의 준비처럼 여러 API 호출이 필요한 작업을 간단한 명령어로 실행할 수 있습니다.
• 아직 정식 지원 제품은 아닙니다. Google Workspace GitHub 조직에서 개발되고 있지만 공식 지원 Google 제품은 아니며, 1.0 버전 이전까지 호환성이 깨지는 변경이 발생할 수 있습니다.

GWS CLI란?

GWS CLI는 Gmail, Google Drive, Calendar, Sheets, Docs 등 Google Workspace 서비스를 터미널에서 관리할 수 있도록 만든 오픈소스 명령줄 도구입니다. Google Drive의 파일을 검색하거나 Gmail 받은편지함을 확인하고, Calendar 일정을 조회하는 작업을 명령어로 처리할 수 있습니다. 

GWS CLI의 명령어는 Google의 Discovery Service를 기반으로 구성됩니다. Discovery Service는 각 Google API가 제공하는 리소스와 기능, 요청 형식을 프로그램이 읽을 수 있는 형태로 제공하는 서비스입니다.

GWS CLI는 이 정보를 불러와 gws drive files list와 같은 명령 구조를 자동으로 만듭니다. 따라서 Google Workspace API에 새로운 기능이나 메서드가 추가되더라도, CLI의 명령어를 처음부터 다시 설계하지 않고 변경된 API 구조를 반영할 수 있습니다.

Google Workspace 팀이 

주도해 개발한 오픈소스 도구 

* 이미지 출처: GWS CLI GitHub 저장소 

GWS CLI는 Google Workspace 팀이 주도해 개발하고, 공식 googleworkspace GitHub 조직을 통해 공개한 오픈소스 도구입니다.

Google이 공식적으로 지원하는 정식 제품은 아니지만, 외부 개발자도 코드와 문서 개선에 참여할 수 있도록 공개되어 있습니다. 다양한 사용자의 의견과 실제 활용 경험이 프로젝트 개선에 반영될 수 있는 구조입니다.

현재 GWS CLI는 활발하게 개발되고 있으며, 1.0 버전으로 발전하는 과정에 있습니다. 따라서 향후 업데이트에 따라 기존 명령어나 인증 방식이 변경될 가능성이 있습니다.

GWS CLI가 주목받는 이유

1. 여러 Google Workspace API를 하나의 CLI로 통합합니다

GWS CLI는 Gmail, Google Drive, Calendar, Sheets, Docs 등 서로 다른 Google Workspace API를 하나의 명령 체계로 제공합니다. 서비스별로 별도의 도구나 SDK를 익히지 않아도 비슷한 구조로 여러 Workspace 기능에 접근할 수 있습니다.

2. Discovery Service를 기반으로 동작합니다

GWS CLI는 명령어를 프로그램 안에 모두 고정하는 대신, Google Discovery Service가 제공하는 API 구조를 읽어 명령 체계를 구성합니다. 새로운 리소스나 메서드가 API에 추가되면 이러한 변경 사항을 비교적 빠르게 반영할 수 있는 구조입니다.

3. 결과를 구조화된 JSON으로 제공합니다

명령 실행 결과는 사람이 읽는 설명문이 아니라 구조화된 JSON 형태로 반환됩니다. 각 데이터의 이름과 계층이 명확하게 구분되기 때문에 셸 스크립트와 자동화 시스템, AI 에이전트가 결과를 분석하고 다음 작업에 활용하기 좋습니다.

4. AI 에이전트와의 연결을 고려해 설계됐습니다

GWS CLI는 단순히 사람이 터미널에서 사용하는 도구에 머물지 않습니다. 구조화된 출력과 일관된 명령 체계, Agent Skill을 제공해 AI 에이전트가 Google Workspace 기능을 호출하고 결과를 처리할 수 있도록 설계됐습니다.

5. 오픈소스로 공개돼 기능을 확장할 수 있습니다

GWS CLI는 Google Workspace 팀이 주도해 개발하고 공식 GitHub 조직에서 공개한 오픈소스 도구입니다. 외부 개발자도 코드와 문서 개선에 참여할 수 있으며, 필요한 기능을 추가하거나 조직의 업무 환경에 맞게 확장할 수 있습니다.

GWS CLI 사용법

* GWS CLI 설치 전 준비사항

GWS CLI를 사용하려면 Google 계정과 Google Cloud 프로젝트가 필요합니다. Gmail, Drive, Calendar처럼 실제로 사용할 Google Workspace API를 프로젝트에서 활성화하고, 계정 접근을 위한 OAuth 인증 정보도 준비해야 합니다.

설치 방식에 따라 필요한 환경은 달라집니다. npm으로 설치하려면 Node.js 18 이상이 필요하고, gws auth setup 명령어로 프로젝트와 인증 설정을 진행하려면 Google Cloud CLI가 설치되어 있어야 합니다.

Node.js를 설치하지 않고 사용할 수도 있습니다. 운영체제에 맞는 실행 파일을 직접 내려받아 설치하면 별도의 npm 환경 없이 GWS CLI를 실행할 수 있습니다.

정리하면 설치 전에 필요한 항목은 다음과 같습니다.

• Google 계정
• Google Cloud 프로젝트
• 사용할 Google Workspace API
• OAuth 인증 정보
• npm 설치 시 Node.js 18 이상
• gws auth setup 사용 시 Google Cloud CLI

GWS CLI 설치 방법

npm으로 설치하기

Node.js가 설치되어 있다면 npm으로 GWS CLI를 설치할 수 있습니다.

설치가 완료되면 버전을 확인합니다. npm 패키지는 운영체제에 맞는 GWS CLI 실행 파일을 내려받아 설치하는 역할을 합니다.

macOS에서 Homebrew로 설치하기

소스 코드에서 설치하기

Rust와 Cargo가 준비되어 있다면 GitHub 저장소의 소스 코드로 설치할 수 있습니다.

처음 사용하는 경우에는 npm이나 GitHub Releases에서 제공하는 실행 파일을 이용하는 것이 비교적 간단합니다.

Google Cloud CLI 설치하기 

GWS CLI를 사용하기 위해서는 GCC CLI가 설치되어 있어야 합니다. 위의 두 명령어를 순서대로 입력해 GCC CLI를 설치합니다.

Google 계정 인증하기

Google Cloud CLI가 설치되어 있다면 위의 명령어를 실행합니다. 

이 명령어는 Google Cloud 프로젝트 설정, 필요한 API 활성화와 OAuth 로그인을 안내합니다. 설정이 끝난 후 계정에 다시 로그인할 때는 다음 명령어를 사용할 수 있습니다.

GWS CLI가 사용할 Google Cloud 프로젝트를 선택하는 단계입니다. Create a new GCP project를 선택한 뒤, 용도를 알아볼 수 있는 프로젝트 ID를 입력하면 다음 인증 단계로 넘어갈 수 있습니다. 

기존 프로젝트를 사용할 수도 있지만, 다른 서비스와 설정이 섞이지 않도록 GWS CLI 전용 프로젝트를 새로 만드는 방법이 가장 관리하기 쉽습니다. 

새 GCP 프로젝트의 프로젝트 ID를 입력하는 단계입니다. 프로젝트 ID를 입력한 뒤 Enter를 누릅니다.

GWS CLI에서 사용할 Google 서비스 API를 고르는 화면입니다. 

• Google Drive
• Gmail
• Google Calendar
• Google Docs
• Google Sheets

개인 Gmail 계정으로 기본 기능을 사용하기 위해 우선 위의 5개만 선택하면 됩니다. 

각 항목에 스페이스바를 누르면 초록색 버튼으로 바뀌면서 선택할 수 있습니다. 선택한 뒤 Enter를 클릭합니다.

OAuth 동의 화면과 OAuth 클라이언트를 직접 만드는 단계입니다. Ctrl을 누른 상태에서 Step A 아래 첫 번째 링크를 클릭합니다. 링크가 열리지 않으면 복사해 브라우저 주소창에 붙여 넣습니다. 

OAuth 동의 화면 설정

Google Cloud 화면이 열립니다. 아래와 같이 설정합니다.

• 앱 이름: GWS CLI
• 사용자 지원 이메일: 현재 사용하는 Gmail 주소
• 대상 또는 User Type: External(외부)
• 개발자 연락처: 현재 사용하는 Gmail 주소

External은 외부 사용자 유형이라는 뜻이지만, 개인 Gmail 계정을 연결할 때 선택하는 항목입니다. 설정 화면은 계속 저장 및 계속을 눌러 완료하면 됩니다.

Test users 또는 테스트 사용자 화면이 나오면 현재 로그인할 Gmail 계정을 추가합니다.

OAuth 클라이언트 만들기 

이제 OAuth 클라이언트를 생성해야합니다. OAuth 클라이언트 만들기 버튼을 클릭합니다. 

• 애플리케이션 유형: 데스크톱 앱
• 이름: GWS CLI Desktop

설정값을 위와 같이 입력하고 만들기 버튼을 클릭합니다.

OAuth 클라이언트 ID가 생성되면, ID를 클릭해 정보 화면으로 들어갑니다. 정보 화면에서 클라이언트 ID와 클라이언트 보안 비밀번호를 복사해 순서대로 터미널에 입력합니다. 이 후 OAuth 로그인 실행 유무 안내가 나오는데, (Y/N) 중 Y를 클릭합니다.

GWS CLI가 사용할 OAuth 권한을 선택하는 화면이 나옵니다. 현재 Recommended가 선택돼 47개 중 28개 권한이 체크된 상태이나 테스트 상태의 OAuth 앱은 권한을 너무 많이 요청하면 인증 화면에서 오류가 발생할 수 있습니다.

개인 Gmail 계정에서 처음 연결하는 단계라면 그대로 진행하지 말고, 우선 읽기 전용 권한만 선택하는 편이 안전합니다. 이를 위해 Recommended를 해제하고 Read Only를 선택합니다. 선택과 해제는 스페이스바를 누르면 할 수 있습니다.

Drive, Gmail, Calendar, Docs, Sheets도 모두 readonly 권한만 선택되어 있어 파일·메일·일정을 조회할 수는 있지만 수정하거나 삭제하지는 못합니다. 선택 개수가 줄어든 것을 확인했으면 Enter를 누릅니다.

이후 브라우저 인증 화면이 열리면 같은 Google 계정을 선택하고 접근 권한을 허용하면 됩니다. 

GWL CLI 인증절차 오류 화면이 나올 경우

로그인한 계정이 ‘테스트 사용자’로 등록되지 않으면 로그인이 되지 않고 인증절차 오류 화면이 나옵니다.

Google Cloud Console 화면으로 돌아가 좌측 사이드 패널에서 '대상’을 클릭한 뒤 테스트 사용자의 + Add users 버튼을 클릭합니다.

사용자 추가 화면에 GWS CLI로 로그인하는 계정을 입력하고 저장을 클릭합니다. 외부 사용자 유형의 OAuth 앱이 테스트 상태라면, 사용할 Google 계정을 테스트 사용자 목록에 추가해야 합니다. 등록을 마친 뒤 현재 차단 화면으로 돌아와 새로고침하세요. 계속 차단되면 터미널에서 인증을 다시 실행합니다. 

화면이 바뀐 것을 볼 수 있습니다. 오른쪽에 있는 계속 버튼을 클릭한 뒤 계정을 연동하고, 이후 GWS CLI에 연결할 Google 계정을 선택하고, Drive·Gmail·Calendar 등에서 허용할 접근 권한 범위를 설정합니다. 

GWS CLI 설치와 Google 계정 인증 설정이 모두 완료되었다는 화면이 나옵니다.

이제 터미널에서 Google Workspace 도구를 사용할 수 있습니다. gws 뒤에 사용할 서비스와 실행할 명령어를 붙이면 실행이 됩니다.

GWS CLI에 명령어를 입력해 도구 사용해보기

1. 최근 Google Drive 파일 확인하기

파일 이름과 ID, MIME Type 등의 정보가 JSON으로 반환됩니다.

2. 오늘 일정 확인하기

특정 시간대를 지정할 수도 있습니다.

3. 읽지 않은 이메일 요약하기

발신자, 제목과 수신 날짜를 중심으로 읽지 않은 이메일을 확인할 수 있습니다.

4. 스프레드시트에 데이터 추가하기

실행하면 스프레드시트 A열에 ‘홍길동’, B열에 ‘완료’가 추가됩니다.  실제 업무에서는 스프레드시트 ID와 입력할 열 순서를 먼저 확인해야 합니다.

5. 파일을 Google Drive에 업로드하기

현재 컴퓨터에 있는 report.pdf 파일이 Google Drive에 업로드되고, Drive에서는 주간 보고서.pdf라는 이름으로 저장됩니다. 

* 위 명령어들은 현재 GWS CLI가 읽기 전용 권한으로 연결되어 있어 바로 실행할 수 없습니다. gws auth login을 다시 실행한 뒤 필요한 쓰기 권한을 추가하면, GWS CLI에서 파일 업로드나 스프레드시트 데이터 추가 등의 작업을 실행할 수 있습니다.

GWS CLI, 실무에서는 이렇게 활용하세요

1. 아침 업무 현황 정리

프로젝트 관리자는 하루를 시작할 때 Calendar 일정과 Tasks를 각각 확인해야 합니다. 이메일로 들어온 중요 요청까지 확인하면 여러 화면을 이동해야 합니다.

GWS CLI의 +standup-report, +agenda, +triage 명령어를 조합하면 당일 일정과 미완료 작업, 읽지 않은 메일을 하나의 데이터 흐름으로 가져올 수 있습니다.

AI 에이전트와 연결할 때는 결과를 요약하게 하되, 메일 발송이나 일정 수정은 별도 승인을 받은 뒤 실행하도록 설정하는 것이 좋습니다.

2. 회의 전 자료 준비

회의 참석자와 일정은 Calendar에 있고, 참고 자료는 Drive나 Docs에 나뉘어 저장되는 경우가 많습니다.

+meeting-prep은 다음 회의의 일정, 참석자와 연결된 문서를 확인하는 업무에 사용할 수 있습니다. 검색 결과에 동명이인의 문서나 오래된 자료가 포함될 수 있으므로, 최종 회의 자료는 사람이 다시 확인해야 합니다.

3. 이메일을 업무 항목으로 전환

고객이나 내부 담당자가 보낸 요청 사항은 Gmail에서 확인한 뒤 Tasks나 프로젝트 관리 도구에 다시 입력해야 합니다.

GWS CLI의 +email-to-task 워크플로를 사용하면 특정 메일을 Google Tasks 항목으로 변환할 수 있습니다. 제목과 마감일, 담당자 정보가 올바르게 작성되었는지 확인한 뒤 저장하는 방식으로 활용할 수 있습니다.

4. 콘텐츠와 데이터 운영 자동화

마케팅팀은 캠페인 데이터는 Sheets에 저장하고, 결과 보고서는 Docs로 작성하며, 최종 파일은 Drive로 공유하는 경우가 많습니다.

GWS CLI를 이용하면 Sheets에 데이터를 추가하고, Docs에 결과를 기록한 뒤, Drive 파일을 Chat에 공유하는 과정을 스크립트로 연결할 수 있습니다.

자동화 과정에서 셀 범위와 문서 ID를 잘못 입력하면 다른 자료가 수정될 수 있습니다. 테스트용 파일에서 먼저 실행하고, 쓰기 작업은 --dry-run이나 별도 승인 단계를 두는 것이 좋습니다.

GWS CLI 사용 시 주의사항

1. 정식 지원 제품이 아니라는 점을 확인해야 합니다

GWS CLI는 현재 공식 지원되는 Google 제품이 아니며, 1.0 이전의 개발 단계에 있습니다. 업데이트 과정에서 명령어, 옵션, 인증 방식이 변경될 수 있으므로 기업 업무에 적용할 때는 버전을 고정하고 업데이트 후 정상 작동 여부를 다시 확인하는 것이 좋습니다.

2. 필요한 권한만 최소한으로 허용해야 합니다

Gmail, Drive, Calendar 등의 권한을 모두 허용하면 GWS CLI나 연결된 AI 에이전트가 접근할 수 있는 데이터 범위도 커집니다. 조회만 필요한 경우에는 읽기 전용 권한을 사용하고, 실제로 사용하지 않는 서비스와 기능은 OAuth 권한 범위에서 제외해야 합니다.

3. 데이터 변경 작업에는 사용자 승인 절차가 필요합니다

메일 발송, 파일 삭제, 일정 생성, 문서 수정 등의 명령은 실제 Google 계정에 바로 반영됩니다. 처음에는 조회 기능만 사용하고, 변경 작업을 실행할 때는 작업 대상과 내용을 사용자에게 먼저 보여준 뒤 승인받도록 구성하는 것이 안전합니다. 지원되는 명령어에서는 --dry-run을 이용해 실행 내용을 미리 확인할 수 있습니다.

4. 외부 콘텐츠와 인증 정보를 안전하게 관리해야 합니다

이메일이나 문서에 포함된 악의적인 지시를 AI 에이전트가 사용자의 요청으로 잘못 인식할 수 있으므로, 외부 콘텐츠의 지시를 그대로 실행해서는 안 됩니다. 

OAuth 인증 파일, 액세스 토큰, 서비스 계정 키도 Git 저장소에 올리지 말고 Secret Manager나 CI 환경변수 등 별도의 비밀정보 관리 기능에 보관해야 합니다.

요즘 주목받는 AI 에이전트 도구가 궁금하다면

Antigravity CLI 사용법, 설치부터 스킬 생성까지 완벽 가이드

Claude Cowork 사용법 총정리, 클로드를 활용한 AI 에이전트로 자동화하기

Hermes Agent 사용법, 설치부터 활용 노하우까지