This document is read via Read from the command (
commands/nopal.md) and is reference material. Refer to this document only when the gws CLI is not installed or authentication has not been done.
1. gws CLI란?
gws (Google Workspace CLI) is an official CLI tool that lets you operate the 9 Google Workspace services from the terminal. Nopal interacts with Google Workspace through this gws CLI.
Key points:
- The gws CLI manages the OAuth token itself.
- The Nopal plugin does not handle the token directly.
- It uses OAuth (user authentication), not an API key or service account.
2. Installation
Prerequisites
- Node.js 18 or higher
- npm or yarn
Installation command
npm install -g @googleworkspace/cli
Verify installation
gws --version
If a version number is output, the installation was successful.
If installation fails
| Symptom | Solution |
|---|---|
command not found: gws |
The npm global path may not be in PATH. npm config get prefix Check and add to PATH. |
| permission error | sudo npm install -g @googleworkspace/cli or using nvm is recommended. |
| Node.js version error | node --versionto check. If below 18, an upgrade is required. |
Guidance rules:
- By default, when
/nopalis run, ifgwsis not installed, it automatically attempts installation. - If automatic installation fails, guide the user on how to install manually.
3. Initial setup (gws auth setup)
gws auth setupis an interactive TUI. It cannot be run with the Bash tool, and the user must be guided to run it directly in the terminal.
3-1. Run
gws auth setup
3-2. 5-step guide
Step 1/5: Check gcloud CLI
- It is detected automatically. If not installed, see https://cloud.google.com/sdk/docs/install .
Step 2/5: Select Google account
- Select the Google account to use.
Step 3/5: Create GCP project
- Select "Create new project" (recommended).
- Project ID rules:
- Starts with a lowercase letter
- Only lowercase letters, numbers, and hyphens (
-) can be used - 6~30자
- Must be globally unique (error if duplicated)
- Recommended format:
nopal-ws-XXXXXX(예:nopal-ws-830621)- Appending a birth date or 6 random digits reduces the chance of collision.
Step 4/5: Select Workspace APIs
- Select all 9 required for Nopal:
- Google Drive, Google Sheets, Gmail, Google Calendar
- Google Docs, Google Slides, Google Tasks, Google Chat, Google Meet
- Do not select the rest (People, Vault, Forms, Keep, etc.).
- The fewer you select, the fewer scopes there are, making authentication easier.
Step 5/5: OAuth credentials (most important)
A. Configure the OAuth consent screen:
- Open the Step A link shown in the terminal or navigate directly: https://console.cloud.google.com/apis/credentials/consent
- User Type: "External" → Create
- Enter app name (e.g., nopal), select support email, leave the rest blank → Save
B. Add test users (Required! If not done, a "Access blocked" 403 error occurs):
- In the consent screen settings, go to the "Test users" tab → "+ Add users"
- Enter your own Gmail address → Save
- Navigate directly: https://console.cloud.google.com/apis/credentials/consent/edit
C. Create OAuth client ID:
- Open the Step B link shown in the terminal or navigate directly: https://console.cloud.google.com/apis/credentials
- "+ Create credentials" → "OAuth client ID"
- Application type: "Desktop app" → Create
- Paste the generated Client ID and Client Secret into the terminal
4. Login (gws auth login)
After setup is complete, proceed with login:
gws auth login
- On the scope selection screen, select "Recommended".
- When the URL is displayed, copy it directly into your browser to open it (it does not open automatically).
- "Google hasn't verified this app" warning → Advanced → Go to app (unsafe) click.
- Log in with your Google account and approve the permissions, then "Authentication successful" is displayed.
Must run after login:
gws auth export --unmasked 2>/dev/null | grep -v '^Using keyring' > ~/.config/gws/credentials.json
This command must be run to create the plain credentials file so that gws can be used in Claude Code.
(gws decrypts the encrypted credentials.encusing the OS Keyring, but the Bash tool in Claude Code may not be able to access the Keyring.)
Note:
gws auth exportoutput may be mixed withUsing keyring backend: keyringlogs, so remove them withgrep -v. If these logs are included, JSON parsing fails.
Verify authentication
gws auth status
If normal, the authenticated Google account email and the list of enabled APIs are displayed.
5. Troubleshooting authentication issues
| Symptom | Cause | Solution |
|---|---|---|
Token expired |
OAuth token expired | gws auth login run again, then gws auth export --unmasked 2>/dev/null | grep -v '^Using keyring' > ~/.config/gws/credentials.json |
Invalid credentials |
Token file corrupted | gws auth logout then log in again |
액세스 차단됨 / Access blocked (403) |
Test user not registered | GCP console (https://console.cloud.google.com/apis/credentials/consent) → Test users → add your own email |
invalid_scope (400) |
Too many scopes (over 25) | Disable unnecessary APIs (https://console.cloud.google.com/apis/dashboard) or create a new project |
No credentials provided (401) |
Keyring inaccessible (headless environment) | gws auth export --unmasked 2>/dev/null | grep -v '^Using keyring' > ~/.config/gws/credentials.json |
| Browser does not open | Automatic URL opening not supported | Copy the URL shown in the terminal directly and paste it into the browser |
| Organization account restriction | Google Workspace administrator policy | Ask the administrator to allow the gws CLI app |
| Project ID duplicate error | ID already in use | Change the random number at the end and retry |
Authentication reset (last resort)
gws auth logout
gws auth setup
Delete all tokens and set up again from scratch.
6. After installation is complete
Once both installation and authentication are complete, /nopal run the command again.
The command automatically detects the authentication status and enters orchestration mode.
Verification checklist:
-
gws --version→ Output version number -
gws auth status→ Display authenticated email + API list -
/nopalRun → Start orchestration