SuperAPI AI Directory

nopal-setup

General & other

View repository

Updated 10-16 09:56

About this skill

Nopal Setup — gws CLI Installation and Authentication Guide

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 /nopal is run, if gws is 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

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:

B. Add test users (Required! If not done, a "Access blocked" 403 error occurs):

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 export output may be mixed with Using keyring backend: keyring logs, so remove them with grep -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
  • /nopal Run → Start orchestration