From 9df60f0c750baeb849c42816e2bd197550f7beab Mon Sep 17 00:00:00 2001 From: Gabriel Rasskin <43894452+grasskin@users.noreply.github.com> Date: Sun, 20 Sep 2026 13:02:42 -0700 Subject: [PATCH] docs(skills): document first-time gws setup --- .changeset/document-gws-skill-setup.md | 5 + .../src/generate_skills.rs | 103 +++++++++++++++++- skills/gws-shared/SKILL.md | 91 +++++++++++++++- 3 files changed, 197 insertions(+), 2 deletions(-) create mode 100644 .changeset/document-gws-skill-setup.md diff --git a/.changeset/document-gws-skill-setup.md b/.changeset/document-gws-skill-setup.md new file mode 100644 index 000000000..f8f915657 --- /dev/null +++ b/.changeset/document-gws-skill-setup.md @@ -0,0 +1,5 @@ +--- +"@googleworkspace/cli": patch +--- + +Document first-time installation and OAuth setup for the Google Chat agent skill. diff --git a/crates/google-workspace-cli/src/generate_skills.rs b/crates/google-workspace-cli/src/generate_skills.rs index ce2654077..ba7b4034f 100644 --- a/crates/google-workspace-cli/src/generate_skills.rs +++ b/crates/google-workspace-cli/src/generate_skills.rs @@ -685,7 +685,96 @@ metadata: ## Installation -The `gws` binary must be on `$PATH`. See the project README for install options. +The `gws` binary must be on `$PATH`. + +```bash +npm install -g @googleworkspace/cli +gws --version +``` + +Install the shared skill together with the service skills you need. A selective +installation does not automatically include `gws-shared`. + +```bash +npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-shared +npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-chat +npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-chat-send +``` + +To install every Workspace skill, use +`npx skills add https://github.com/googleworkspace/cli`. + +## First-time setup + +Check the current state before starting another login flow: + +```bash +gws auth status +``` + +If no credentials exist, install and authenticate the Google Cloud CLI. On +macOS with Homebrew: + +```bash +brew install --cask google-cloud-sdk +gcloud auth login +``` + +Then run the guided setup: + +```bash +gws auth setup --login +``` + +The setup creates or selects a Google Cloud project, enables the chosen +Workspace APIs, and configures an OAuth desktop client. Select only the APIs +needed for the task. For a Chat-to-Slides workflow, enable Google Chat, Google +Drive, and Google Slides. + +### Setup interruptions + +- If project creation says the account has not accepted Google Cloud Terms, + sign in to `https://console.cloud.google.com/` with the same account, accept + the terms, and retry the setup. +- If the setup requests manual OAuth configuration, open the consent screen for + the selected project. Use an Internal audience when the Workspace permits it. + Otherwise use External and add the authenticating account as a test user. +- Create an OAuth client with application type **Desktop app**, download its + JSON, and save it as `~/.config/gws/client_secret.json` with mode `600`. +- Never print the client secret, refresh token, or decrypted credentials. Move + the downloaded JSON directly instead of displaying its contents. + +Example secure install of the downloaded client file: + +```bash +mkdir -p ~/.config/gws +install -m 600 /path/to/client_secret.json ~/.config/gws/client_secret.json +``` + +Authorize explicit scopes after installing the OAuth client. Prefer +`--scopes` for Chat because some `gws` releases have omitted Chat scopes when +using `--services chat`. + +Chat read access: + +```bash +gws auth login --scopes \ + 'https://www.googleapis.com/auth/chat.spaces.readonly,https://www.googleapis.com/auth/chat.messages.readonly' +``` + +Chat discovery plus reading Drive links and editing Google Slides: + +```bash +gws auth login --scopes \ + 'https://www.googleapis.com/auth/chat.spaces.readonly,https://www.googleapis.com/auth/chat.messages.readonly,https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/presentations' +``` + +Verify the result without exposing credentials: + +```bash +gws auth status +gws chat spaces list --params '{"pageSize":1000}' +``` ## Authentication @@ -1291,6 +1380,18 @@ mod tests { fm.contains("- gws"), "shared skill frontmatter should contain '- gws'" ); + assert!( + content.contains("npm install -g @googleworkspace/cli"), + "shared skill should document CLI installation" + ); + assert!( + content.contains("gws auth setup --login"), + "shared skill should document first-time authentication setup" + ); + assert!( + content.contains("https://www.googleapis.com/auth/chat.spaces.readonly"), + "shared skill should document explicit Chat scopes" + ); } #[test] diff --git a/skills/gws-shared/SKILL.md b/skills/gws-shared/SKILL.md index dc6a32237..8a9d4acfe 100644 --- a/skills/gws-shared/SKILL.md +++ b/skills/gws-shared/SKILL.md @@ -14,7 +14,96 @@ metadata: ## Installation -The `gws` binary must be on `$PATH`. See the project README for install options. +The `gws` binary must be on `$PATH`. + +```bash +npm install -g @googleworkspace/cli +gws --version +``` + +Install the shared skill together with the service skills you need. A selective +installation does not automatically include `gws-shared`. + +```bash +npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-shared +npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-chat +npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-chat-send +``` + +To install every Workspace skill, use +`npx skills add https://github.com/googleworkspace/cli`. + +## First-time setup + +Check the current state before starting another login flow: + +```bash +gws auth status +``` + +If no credentials exist, install and authenticate the Google Cloud CLI. On +macOS with Homebrew: + +```bash +brew install --cask google-cloud-sdk +gcloud auth login +``` + +Then run the guided setup: + +```bash +gws auth setup --login +``` + +The setup creates or selects a Google Cloud project, enables the chosen +Workspace APIs, and configures an OAuth desktop client. Select only the APIs +needed for the task. For a Chat-to-Slides workflow, enable Google Chat, Google +Drive, and Google Slides. + +### Setup interruptions + +- If project creation says the account has not accepted Google Cloud Terms, + sign in to `https://console.cloud.google.com/` with the same account, accept + the terms, and retry the setup. +- If the setup requests manual OAuth configuration, open the consent screen for + the selected project. Use an Internal audience when the Workspace permits it. + Otherwise use External and add the authenticating account as a test user. +- Create an OAuth client with application type **Desktop app**, download its + JSON, and save it as `~/.config/gws/client_secret.json` with mode `600`. +- Never print the client secret, refresh token, or decrypted credentials. Move + the downloaded JSON directly instead of displaying its contents. + +Example secure install of the downloaded client file: + +```bash +mkdir -p ~/.config/gws +install -m 600 /path/to/client_secret.json ~/.config/gws/client_secret.json +``` + +Authorize explicit scopes after installing the OAuth client. Prefer +`--scopes` for Chat because some `gws` releases have omitted Chat scopes when +using `--services chat`. + +Chat read access: + +```bash +gws auth login --scopes \ + 'https://www.googleapis.com/auth/chat.spaces.readonly,https://www.googleapis.com/auth/chat.messages.readonly' +``` + +Chat discovery plus reading Drive links and editing Google Slides: + +```bash +gws auth login --scopes \ + 'https://www.googleapis.com/auth/chat.spaces.readonly,https://www.googleapis.com/auth/chat.messages.readonly,https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/presentations' +``` + +Verify the result without exposing credentials: + +```bash +gws auth status +gws chat spaces list --params '{"pageSize":1000}' +``` ## Authentication