Installation

Install the Google Workspace CLI via npm or build from source

Installation

The Google Workspace CLI can be installed via npm (recommended) or built from source using Cargo.

System Requirements

Operating System

• Linux: All major distributions (Ubuntu, Debian, Fedora, Arch, etc.)
• macOS: 10.15 (Catalina) or later
• Windows: Windows 10/11 with WSL2 recommended

Node.js (for npm installation)

• Version: Node.js 18 or later
• Check your version: node --version
• Download from nodejs.org

Rust (for source installation)

• Version: Rust 1.70 or later (2021 edition)
• Check your version: cargo --version
• Install from rustup.rs

gcloud CLI (for auth setup)

• Required for gws auth setup command
• Optional if you configure OAuth manually
• Install from Google Cloud SDK

Install via npm (Recommended)

The easiest way to install gws is through npm:

npm

npm install -g @googleworkspace/cli

The npm package includes pre-built binaries for Linux, macOS, and Windows. No Rust toolchain required.

Verify Installation

Confirm the CLI is installed correctly:

Terminal

gws --version

Expected output:

Output

gws 0.3.3

Build from Source

If you want to build from source or contribute to development, use Cargo:

1. Clone the repository

   Terminal

   git clone https://github.com/googleworkspace/cli.git
   cd cli
   
2. Build and install

   Terminal

   cargo install --path .
   

   This compiles the Rust binary and installs it to ~/.cargo/bin/gws.

3. Verify installation

   Terminal

   gws --version
   

Building from source gives you the latest unreleased features but may include breaking changes.

Development Build

For active development, build without installing:

Terminal

cargo build                       # Debug build → target/debug/gws
cargo build --release             # Optimized build → target/release/gws
cargo clippy -- -D warnings       # Lint check
cargo test                        # Run unit tests

Then run the binary directly:

Terminal

./target/debug/gws --help

Package Managers

Additional package managers (Homebrew, Chocolatey, Snap) are planned but not yet available. For now, use npm or Cargo.

Planned Support

• Homebrew (macOS/Linux): brew install googleworkspace/tap/gws
• Chocolatey (Windows): choco install gws
• Snap (Linux): snap install gws

Check the GitHub repository for updates.

Configuration Directory

After installation, gws creates a configuration directory on first run:

Platform	Location
Linux	~/.config/gws/
macOS	~/Library/Application Support/gws/
Windows	%APPDATA%\gws\

This directory stores:

• client_secret.json: OAuth client credentials (if configured manually)
• Discovery cache: API discovery documents (cached for 24 hours)
• Encrypted credentials: OAuth tokens secured with OS keyring

Credentials are encrypted at rest using AES-256-GCM with keys stored in your OS keyring.

Updating

Keep gws up to date to get the latest features and bug fixes.

Update via npm

Terminal

npm update -g @googleworkspace/cli

Update from source

Terminal

cd cli
git pull origin main
cargo install --path .

Uninstall

Remove npm installation

Terminal

npm uninstall -g @googleworkspace/cli

Remove Cargo installation

Terminal

cargo uninstall gws

Remove configuration

To completely remove all stored credentials and cache:

Linux/macOS

rm -rf ~/.config/gws

This will delete all stored OAuth credentials. You’ll need to re-authenticate after reinstalling.

Troubleshooting

Command not found: gws

Problem: The gws binary is not in your PATH.

Solution:

• For npm: Ensure npm global bin directory is in PATH
  npm config get prefix  # Should show a directory in your PATH
  
• For Cargo: Ensure ~/.cargo/bin is in your PATH
  echo $PATH | grep cargo
  

Permission denied errors

Problem: Insufficient permissions to install globally.

Solution:

• Use sudo for npm (not recommended):
  sudo npm install -g @googleworkspace/cli
  
• Or configure npm to use a user directory (recommended):
  npm config set prefix ~/.npm-global
  export PATH=~/.npm-global/bin:$PATH
  

Rust compilation errors

Problem: Cargo build fails with dependency errors.

Solution:

• Update Rust to the latest stable version:
  rustup update stable
  
• Clean build artifacts and retry:
  cargo clean
  cargo build --release
  

Next Steps

Quickstart

Set up authentication and run your first command

Authentication

Configure Google Cloud OAuth credentials