Skip to main content

​
Installation

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

​
System Requirements

  • Linux: All major distributions (Ubuntu, Debian, Fedora, Arch, etc.)
  • macOS: 10.15 (Catalina) or later
  • Windows: Windows 10/11 with WSL2 recommended
  • Version: Node.js 18 or later
  • Check your version: node --version
  • Download from nodejs.org
  • Version: Rust 1.70 or later (2021 edition)
  • Check your version: cargo --version
  • Install from rustup.rs
  • Required for gws auth setup command
  • Optional if you configure OAuth manually
  • Install from Google Cloud SDK
The easiest way to install gws is through 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:
PlatformLocation
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: 
rm -rf ~/.config/gws
This will delete all stored OAuth credentials. You’ll need to re-authenticate after reinstalling.

​
Troubleshooting

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
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
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