praxis-gws

name	praxis-gws
description	Google Workspace CLI for Gmail, Calendar, and Drive. Official Google APIs wrapper for secure, direct API access without third-party proxies. Use when managing emails, calendar events, or searching Google Drive files. Supports Gmail search operators, label management, drafts, calendar event creation, and Drive file search.

Praxis Google Workspace CLI

Official Google APIs wrapper for Gmail, Calendar, and Drive. Direct connection to Google — no third-party proxy.

Setup

1. Create Google Cloud Project

1. Go to https://console.cloud.google.com
2. Create a new project
3. Enable these APIs:
   • Gmail API
   • Google Calendar API
   • Google Drive API

2. Create OAuth Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Application type: Desktop app
4. Download the JSON file

3. Configure the CLI

praxis-gws auth credentials /path/to/client_secret.json

4. Authenticate

praxis-gws gmail labels

This will output a Google OAuth URL. Open it in your browser, authorize the app, and paste the authorization code back.

Usage

Gmail Commands

Search messages:

praxis-gws gmail search "is:unread from:example.com"
praxis-gws gmail search "subject:meeting has:attachment" --max 20

Get message:

praxis-gws gmail get <messageId>

Send email:

praxis-gws gmail send "[e-mail]" "Subject" "Body text"

Create draft:

praxis-gws gmail draft "[e-mail]" "Subject" "Draft body"

List labels:

praxis-gws gmail labels

Modify labels:

praxis-gws gmail modify <messageId> --add STARRED --remove UNREAD

Calendar Commands

List events:

praxis-gws calendar list primary --max 10
praxis-gws calendar list primary --from "2026-02-22T00:00:00" --to "2026-03-01T23:59:59"

Create event:

praxis-gws calendar create primary "Meeting Title" \
  --from "2026-02-25T14:00:00" \
  --to "2026-02-25T15:00:00"

Drive Commands

Search files:

praxis-gws drive search "name contains 'project'"
praxis-gws drive search "mimeType = 'application/vnd.google-apps.document'"

Get file metadata:

praxis-gws drive get <fileId>

Gmail Search Operators

• is:unread - Unread messages
• is:starred - Starred messages
• from:[e-mail] - From specific sender
• to:[e-mail] - To specific recipient
• subject:keyword - Subject contains keyword
• after:2026/01/01 - After date
• before:2026/12/31 - Before date
• has:attachment - Has attachments
• in:inbox - In inbox
• label:important - With specific label

Common Labels

• INBOX - Inbox
• SENT - Sent mail
• DRAFT - Drafts
• STARRED - Starred
• UNREAD - Unread
• IMPORTANT - Important
• TRASH - Trash
• SPAM - Spam

Security

• OAuth tokens stored locally in ~/.config/praxis-gws/
• Direct API connection to Google (no proxy)
• Uses official googleapis Node.js library
• Required scopes:
  • https://www.googleapis.com/auth/gmail.modify
  • https://www.googleapis.com/auth/calendar
  • https://www.googleapis.com/auth/drive.readonly

Troubleshooting

Error: credentials.json not found → Run praxis-gws auth credentials /path/to/client_secret.json

Error: Invalid grant / Token expired → Delete ~/.config/praxis-gws/token.json and re-run to trigger new OAuth flow

"Google hasn't verified this app" warning → Click Advanced → Go to [project name] (unsafe) to proceed

CLI Script

The CLI is available at:

scripts/praxis-gws.js

Requires Node.js and the googleapis npm package:

npm install -g googleapis