Gws Admin Reports

What Is This?

Overview

Gws Admin Reports is a command-line skill built on top of the Google Workspace Admin SDK that provides direct access to audit logs and usage reports for Google Workspace environments. It wraps the reports_v1 API surface into a consistent CLI interface, allowing administrators and developers to query activity data, user behavior, and service usage without navigating the Google Admin Console manually. The skill is part of the broader gws CLI toolset and follows the same authentication and global flag conventions established across the suite.

The skill exposes structured access to two primary data categories: audit logs, which record administrative and user actions across Google services, and usage reports, which aggregate metrics about how services and accounts are being used over time. Both categories are accessible through a unified command pattern, making it straightforward to integrate report queries into scripts, pipelines, and monitoring workflows.

Because the skill relies on the Google Workspace Admin SDK, it inherits the permission model and OAuth scopes defined by that API. Administrators must ensure that the authenticated account has the appropriate reporting privileges before running commands. The companion skill gws-shared handles authentication setup and should be configured before using this skill.

Who Should Use This

• Google Workspace administrators who need programmatic access to audit trails and compliance data
• Security engineers building automated log review or anomaly detection pipelines
• DevOps engineers integrating Workspace usage metrics into dashboards or alerting systems
• Compliance officers who require regular exports of administrative activity for audit purposes
• Developers building internal tooling that depends on Workspace activity data
• IT operations teams automating routine reporting tasks across large user bases

Why Use It?

Problems It Solves

• Manual log review through the Admin Console is time-consuming and does not scale for large organizations or frequent audits
• Extracting usage data for custom reporting requires API integration that is complex to set up from scratch
• Scheduled compliance exports are difficult to automate without a reliable CLI interface
• Correlating activity across multiple Google services requires querying several report types in sequence, which is cumbersome without scripting support
• Monitoring for specific administrative actions, such as privilege changes or data exports, requires consistent and repeatable query patterns

Core Highlights

• Provides CLI access to the full reports_v1 API surface
• Supports both activity (audit) and usage report resource types
• Follows the standard gws command pattern for consistency across the toolset
• Integrates with the shared authentication layer from gws-shared
• Outputs structured data suitable for piping into JSON processors or log aggregators
• Supports filtering by date, user, event type, and application name
• Enables automation of compliance and security reporting workflows
• Lightweight dependency requiring only the gws binary

How to Use It?

Basic Usage

The core command pattern follows the structure below:

gws admin-reports <resource> <method> [flags]

To list available activities for the Admin application:

gws admin-reports activities list --applicationName admin

To retrieve usage reports for users on a specific date:

gws admin-reports userUsageReport get --userKey all --date 2024-06-01

To view all available subcommands and flags:

gws admin-reports --help

Specific Scenarios

Scenario 1: Exporting login audit logs for a date range

Security teams can extract login activity for all users and pipe the output into a file for further analysis:

gws admin-reports activities list --applicationName login --startTime 2024-06-01T00:00:00Z --endTime 2024-06-07T23:59:59Z > login_audit.json

Scenario 2: Monitoring Drive activity for a specific user

To investigate file access or sharing events for a particular account:

gws admin-reports activities list --applicationName drive --actorIpAddress "" --userKey user@example.com

Real-World Examples

• A compliance team schedules a weekly cron job that exports admin activity logs and uploads them to a secure storage bucket for retention purposes.
• A security engineer queries login reports nightly and pipes results through jq to flag accounts with suspicious access patterns.
• An IT administrator pulls customer usage reports before quarterly business reviews to summarize service adoption across departments.

Important Notes

Requirements

• The gws binary must be installed and available in the system PATH
• A Google Workspace account with reporting privileges is required
• OAuth credentials must be configured through the gws-shared authentication setup
• The Admin SDK Reporting API must be enabled in the associated Google Cloud project