Praxis Google Workspace

Google Workspace CLI for Gmail, Calendar, and Drive. Official Google APIs wrapper for secure, direct API access without third-party proxies. Use when managin...

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