SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsgws-korean-setup

gws-korean-setup

Office & productivity

View repository

Updated 10-15 20:10

About this skill

Google Workspace CLI (gws) Installation and Setup

A step-by-step guide for users installing the gws CLI for the first time. It proceeds in a total of 6 phases, and at the end of each phase, it verifies that the installation is correct.

Argument Handling

$ARGUMENTSparses the following flags:

  • --skip-gcloud → Skips Phase 2 (gcloud installation)
  • --skip-skills → Skips Phase 5 (Claude Code skill installation)

Phase 1: Install gws CLI

gws is distributed as an npm package. Node.js must be installed.

1-1. Check if already installed

which gws && gws --version
  • On Windows, check with where gws.
  • If the version is output, proceed directly to Phase 2.

1-2. Installation

npm install -g @googleworkspace/cli

When installation fails:

Symptom Solution
npm: command not found Node.js is not installed. Install the LTS version first from https://nodejs.org/ .
EACCES: permission denied macOS/Linux: sudo npm install -g @googleworkspace/cli. Windows: Reopen the terminal with administrator privileges and try again.

1-3. Verify installation

gws --version

If the version number is output, it is successful.

Phase 2: Install gcloud CLI

--skip-gcloudIf so, skip this Phase.

gcloud is a tool for managing Google Cloud Platform (GCP) projects. Since a GCP project is required for gws's OAuth setup, it is convenient to install it in advance.

2-1. Check if already installed

gcloud --version
  • On Windows, check with where gcloud.
  • If the version is output, proceed directly to 2-5 (initial login).

2-2. Check OS

AskUserQuestionCheck the OS with:

I will install the gcloud CLI. Please tell me the OS you are using:

  1. macOS Apple Silicon (M1/M2/M3/M4)
  2. macOS Intel
  3. Linux x86_64
  4. Linux ARM
  5. Windows

2-3. macOS / Linux Installation

Download from the URL matching your OS:

OS Download URL
macOS Apple Silicon https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-arm.tar.gz
macOS Intel https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-x86_64.tar.gz
Linux x86_64 https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz
Linux ARM https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-arm.tar.gz 
# 다운로드
curl -O {위 테이블에서 선택한 URL}

# 압축 해제
tar -xzf google-cloud-cli-*.tar.gz

# 설치 (대화형 프롬프트가 나온다)
./google-cloud-sdk/install.sh

Items the installation script asks about:

  • "Modify profile to update your $PATH?" → Y input
  • Shell profile path → Just press Enter (accept the default)

After installation, apply PATH to the current shell:

source ~/.zshrc   # zsh
source ~/.bashrc  # bash

2-4. Windows Installation

Run the following two commands in order in PowerShell:

# 1. 설치 프로그램 다운로드
(New-Object Net.WebClient).DownloadFile("https://dl.google.com/dl/cloudsdk/channels/rapid/GoogleCloudSDKInstaller.exe", "$env:Temp\GoogleCloudSDKInstaller.exe")

# 2. 설치 프로그램 실행
& $env:Temp\GoogleCloudSDKInstaller.exe

When the installation screen appears:

  1. Proceed by clicking Next with the default options
  2. On the last screen, uncheck "Run gcloud init" (handled separately in Phase 3)
  3. Finish click

After installation, apply PATH to the current shell:

$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

2-5. Verify installation and initial login

gcloud --version

If the version appears, perform the initial login:

gcloud auth login

When the browser opens, log in with your Google account. This authentication is used when accessing the GCP project in the next step (OAuth setup).

Phase 3: OAuth Setup (gws auth setup)

In this step, you configure OAuth authentication so that the Google API can be used. It may look complicated at first, but gws auth setup the command handles most of it automatically.

Before running it, give the user an overview of the entire flow:

Now we will set up OAuth authentication. A total of 5 steps proceed automatically:

  1. Select or create a new GCP project
  2. Configure the OAuth consent screen (set app name, user type)
  3. Enable Google APIs (Gmail, Drive, Sheets, Docs, etc.)
  4. Create an OAuth client ID
  5. Save the credential file

Most of it is automatic, and you only need to select a few things yourself.

3-1. Check the GCP project

AskUserQuestionto check:

Do you have an existing GCP project?

  • If you do → tell me the project ID (e.g., my-gws-project)
  • If you do not have one or do not know → we will create a new one (Enter)

3-2. Run setup

# 기존 프로젝트가 있는 경우
gws auth setup --project {PROJECT_ID} --login

# 새 프로젝트를 생성하는 경우
gws auth setup --login

3-3. Guide to interactive prompts

While the command is running, a setup screen opens in the browser. Guide the user through the following order:

  1. GCP project: select an existing project or enter a new name
  2. OAuth consent screen — in the browser, enter the following in order:
    1. App name: choose any name you like (e.g., "GWS CLI", "My Workspace", etc. — anything is fine)
    2. User support email: select the email of the currently logged-in Google account
    3. Developer contact email: enter the same email
    4. Audience (User Type):
      • Company/school Google Workspace account → Internal select (recommended, no additional setup required)
      • Personal Gmail (@gmail.com) → External select
    5. Click Create → leave the remaining items at their default values and Save and continue click through to the end
    6. Only if you selected External: you need to register a test user
      • OAuth consent screen → Audience 탭 → Test users section
      • Add users click → add your own Gmail to use for sign-in → save
      • If you skip this step, in Phase 4 "Access blocked: Authorization error" occurs
  3. API activation: Gmail, Drive, Sheets, Docs, Calendar, etc. — handled automatically
  4. OAuth client ID: automatically created with the Desktop app type
  5. client_secret.json save: When the client ID and secret are displayed on the screen, Download JSON click the button, or copy the displayed JSON

3-4. Save client_secret.json

Save the downloaded or copied JSON to ~/.config/gws/client_secret.json:

# 디렉토리가 없으면 생성
mkdir -p ~/.config/gws

# 복사한 JSON을 붙여넣기 (Ctrl+V 후 Ctrl+D로 저장)
cat > ~/.config/gws/client_secret.json

Windows:

mkdir -Force "$env:USERPROFILE\.config\gws"

# 메모장으로 열어서 JSON 붙여넣기 후 저장
notepad "$env:USERPROFILE\.config\gws\client_secret.json"

3-5. Verify settings

ls -la ~/.config/gws/client_secret.json

If the file is visible, it's a success.

Phase 4: Login (gws auth login)

Now that OAuth setup is done, actually log in to the Google account.

4-1. Select authentication scopes

AskUserQuestionguides with:

Please select which Google services to access:

  1. Only necessary services (recommended) — Gmail, Drive, Sheets, Calendar, Docs
  2. Read-only — read-only for all services
  3. Full permissions — read/write for all services (a restricted_client warning may appear)

Depending on the selection, run the command in the background(run_in_background: true). This is to prevent Claude from stalling while waiting for the authentication URL.

# 1번 선택
gws auth login -s gmail,drive,sheets,calendar,docs

# 2번 선택
gws auth login --readonly

# 3번 선택
gws auth login --full

4-2. Log in from the browser

When the command runs in the background, guide the user:

The authentication URL is in the Bash output. Press Ctrl+O to expand the output, then copy the URL and paste it into your browser. Let me know when you've completed authentication in the browser.

When the authentication page opens in the browser, proceed in the following order:

  1. Select a Google account
  2. "This app isn't verified by Google" warning appears — this is normal. Personal OAuth apps don't go through Google review, so this warning always appears.
  3. "Advanced" click
  4. "Go to (app name) (unsafe)" click
  5. Review the requested permissions and "Allow" click

4-3. Verify login

When the user says they've completed authentication, verify with gws auth status:

gws auth status

If the authenticated account and scopes are displayed, it's a success.

4-4. Simple operation test

# Gmail: 최근 메일 1건 조회
gws gmail users.messages list --userId me --maxResults 1

# Drive: 파일 1건 조회
gws drive files list --pageSize 1

If results appear, gws is working properly.

Phase 5: Install Claude Code skills

--skip-skillsIf so, skip this Phase.

If you install gws's Claude Code skills, you can use commands like /gws-gmail-send, /gws-drive directly in Claude Code.

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

After installation, restart Claude Code and the gws-* skills will appear in the / menu.

Phase 6: Korean encoding guide

Guide the key rules to know when handling Korean text with gws. For details, see the /gws-korean-encoding skill.

Guide the user on the following key points:

3 things you must know

  1. Korean names in email addresses — RFC 2047 Base64 encoding is required

    # "홍길동 <hong@example.com>" → 이렇게 인코딩
=?UTF-8?B?7ZmN6ri464+Z?= <hong@example.com>

    # 인코딩 생성 방법
echo -n "홍길동" | base64

  2. Wrap Korean parameters in double quotes

    gws gmail users.messages send --userId me --subject "회의 안내"

  3. Use a temporary file for long Korean text

    echo "긴 본문..." > /tmp/body.txt
gws gmail users.messages send --userId me --bodyFile /tmp/body.txt

If a problem occurs where Korean text is garbled, /gws-korean-encoding refer to the skill's debugging checklist.

Completion check

When all Phases are finished, perform a final check:

gws --version
gcloud --version
gws auth status
ls ~/.config/gws/client_secret.json

Show the results to the user as a summary table:

Item Status Notes
gws CLI ✅ / ❌ Version
gcloud CLI ✅ / ❌ / ⏭️ skipped Version
OAuth setup ✅ / ❌ Whether client_secret.json exists
Auth login ✅ / ❌ Authorized scopes
Claude Code skill ✅ / ❌ / ⏭️ skipped Number of gws-* skills
Korean encoding ℹ️ Guidance complete —

Troubleshooting

For detailed troubleshooting, refer to references/troubleshooting.md.

Frequently occurring issues:

Symptom Solution
gws: command not found npm config get prefix → PATH에 {prefix}/bin Add
gcloud: command not found Open a new terminal or source ~/.zshrc
restricted_client warning Normal. Only accounts registered as test users can be used
invalid_grant Token expired. gws auth login Rerun
PERMISSION_DENIED gws auth setupAfter reactivating the API with gws auth login
Command not recognized on Windows Open a new PowerShell/CMD. Check PATH