gws-with-audit-log

0.0.5 verified Mon Apr 27 auth: no javascript

A CLI tool for interacting with Google Workspace APIs (Gmail, Drive, Calendar, etc.) with built-in audit logging. Current stable version is v0.22.5. Released as part of the googleworkspace/cli project with regular releases every 1-2 weeks. Key differentiators: dynamic command surface generated from Google Discovery Service, audit log support for tracking commands, prebuilt binaries with native OS keychain integration. ESM-only via npm package or direct binary download.

Common errors

error TypeError: gws.auth.login is not a function ↓

cause Using require() instead of import, or wrong import path.

fix

Use: import gws from 'gws-with-audit-log' (ESM only)

error Error: [gws] No credentials found. Run 'gws auth login' first. ↓

cause Missing OAuth tokens; --audit-log requires prior authentication.

fix

Run: gws auth login with required scopes

error SyntaxError: Cannot use import statement outside a module ↓

cause Node.js project not configured for ESM.

fix

Add "type": "module" to package.json or use .mjs extension.

error gws: command not found ↓

cause Binary not installed or not in PATH after npm install.

fix

Install globally: npm install -g gws-with-audit-log

Warnings

gotcha Requires Node >=14 and ESM imports. Do not use require(). ↓

fix Use import syntax and Node >=14.

breaking v0.22.0 changed the --draft flag behavior for Gmail helpers. Existing scripts may send emails immediately if not updated. ↓

fix Add --draft flag explicitly if saving drafts is intended.

breaking v0.18.0 introduced auto-population of From header with display name. May change sender display unexpectedly. ↓

fix Use --from with explicit display name to override.

breaking v0.22.3 removed fallback .encryption_key file on macOS/Windows. Credentials cannot be decrypted if keychain fails. ↓

fix Ensure native OS keychain is available and not corrupted.

deprecated Audit logging flags may change in future versions. Currently experimental. ↓

fix Watch release notes for stabilization.

Install

npm install gws-with-audit-log

yarn add gws-with-audit-log

pnpm add gws-with-audit-log

Imports

gws

wrong

const gws = require('gws-with-audit-log')

correct

import gws from 'gws-with-audit-log'

ESM-only since v0.22.4. CJS require() will fail.

GwsClient

wrong

import GwsClient from 'gws-with-audit-log'

correct

import { GwsClient } from 'gws-with-audit-log'

Named export for programmatic use.

AuditLog

wrong

const AuditLog = require('gws-with-audit-log').AuditLog

correct

import { AuditLog } from 'gws-with-audit-log'

Audit logging module for tracking CLI commands.

Quickstart

Shows authentication, sending an email via Gmail API, and enabling audit logging.

import gws from 'gws-with-audit-log';

// Authenticate with Google Workspace
await gws.auth.login({
  clientId: process.env.GOOGLE_CLIENT_ID ?? '',
  clientSecret: process.env.GOOGLE_CLIENT_SECRET ?? '',
  scopes: ['https://www.googleapis.com/auth/gmail.send']
});

// Send an email with audit log
const result = await gws.gmail.send({
  to: 'user@example.com',
  subject: 'Hello',
  body: 'Test email',
  auditLog: true
});

console.log('Sent message ID:', result.id);