Gws Shared

What Is This?

Overview

Gws Shared is a foundational reference layer within the gws command-line interface for Google Workspace. It defines the shared patterns that apply across all gws subcommands, covering authentication methods, global flags, and output formatting conventions. Rather than being a standalone feature, it serves as the common ground that makes every other gws command consistent and predictable.

The gws CLI is a tool for interacting with Google Workspace APIs from the terminal. Gws Shared captures the cross-cutting concerns that developers and administrators encounter regardless of which specific Workspace service they are working with. Understanding these shared patterns reduces friction when switching between subcommands and helps users write reliable scripts and automation pipelines.

At version 0.22.3, the shared layer covers two primary authentication strategies, a set of global flags that modify command behavior, and output formatting options that control how results are presented. Mastering these fundamentals unlocks the full potential of the gws CLI across all supported Google Workspace services.

Who Should Use This

• System administrators who manage Google Workspace environments and need reliable CLI tooling for bulk operations and audits.
• DevOps engineers building automation pipelines that interact with Google Workspace APIs as part of CI/CD workflows.
• Developers integrating Google Workspace data into internal tools and needing a consistent command-line interface for testing and scripting.
• Security engineers who audit Workspace configurations and require scriptable, repeatable access patterns.
• IT support teams performing routine account and resource management tasks at scale without relying on the web console.

Why Use It?

Problems It Solves

• Inconsistent authentication setup across different Workspace API calls, leading to repeated credential configuration.
• Lack of a unified output format when piping gws results into other tools such as jq, grep, or log aggregators.
• Difficulty managing global behavior like verbosity or output destination without rewriting individual commands.
• Confusion about which credential type to use in interactive versus automated contexts, causing authentication failures in production pipelines.

Core Highlights

• Supports browser-based OAuth for interactive sessions and service account credentials for automated workflows.
• Global flags apply consistently across all subcommands, reducing the need to memorize per-command options.
• Output formatting options allow structured data output suitable for downstream processing.
• The GOOGLE_APPLICATION_CREDENTIALS environment variable integrates with standard Google Cloud credential patterns.
• Shared patterns are documented in one place, making onboarding faster for new team members.
• The binary-based design keeps the tool portable and easy to include in containerized environments.

How to Use It?

Basic Usage

Authentication is the first step before running any gws command. Two methods are available depending on the context.

## Browser-based OAuth for interactive use
gws auth login

## Service account authentication using an environment variable
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

Once authenticated, global flags can be appended to any command to modify its behavior.

## Run a command with verbose output
gws --verbose users list

## Specify an output format
gws --format json users list

Specific Scenarios

Scenario 1: Automated pipeline authentication. In a CI/CD environment, browser-based OAuth is not practical. Set the GOOGLE_APPLICATION_CREDENTIALS variable in the pipeline environment and the gws CLI will use the service account automatically without any interactive prompts.

Scenario 2: Debugging a failing command. When a command returns unexpected results, add the --verbose flag to see detailed request and response information, which helps identify permission issues or malformed inputs.

Real-World Examples

Example 1: A DevOps engineer exports a list of all Workspace users in JSON format and pipes it into jq to extract email addresses for a downstream provisioning script.

gws --format json users list | jq '.[].email'

Example 2: A system administrator runs a scheduled audit script using a service account, ensuring no manual login is required during off-hours execution.

export GOOGLE_APPLICATION_CREDENTIALS=/etc/gws/sa-key.json
gws users list --domain example.com

When to Use It?

Use Cases

• Setting up authentication before running any gws subcommand in a new environment.
• Configuring service account credentials for automated or scheduled Workspace management tasks.
• Formatting command output for integration with data processing pipelines.
• Applying verbose logging during development and debugging sessions.
• Standardizing CLI behavior across team members by documenting shared flag conventions.
• Running gws inside Docker containers where browser-based OAuth is unavailable.

Important Notes

Requirements

• The gws binary must be installed and available on $PATH.
• A valid Google Workspace account or service account with appropriate API permissions is required.
• For service account authentication, the JSON key file must be accessible at the path specified in GOOGLE_APPLICATION_CREDENTIALS.