praxis-gws

适用于 Gmail、日历和云端硬盘的 Google Workspace CLI。官方 Google API 包装器，无需第三方代理即可安全、直接访问 API。在管理电子邮件、日历活动或搜索 Google 云端硬盘文件时使用。支持 Gmail 搜索运算符、标签管理、草稿、日历事件创建和云端硬盘文件搜索。

# 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

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

### 4. Authenticate

```bash
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:**
```bash
praxis-gws gmail search "is:unread from:example.com"
praxis-gws gmail search "subject:meeting has:attachment" --max 20
```

**Get message:**
```bash
praxis-gws gmail get <messageId>
```

**Send email:**
```bash
praxis-gws gmail send "recipient@example.com" "Subject" "Body text"
```

**Create draft:**
```bash
praxis-gws gmail draft "recipient@example.com" "Subject" "Draft body"
```

**List labels:**
```bash
praxis-gws gmail labels
```

**Modify labels:**
```bash
praxis-gws gmail modify <messageId> --add STARRED --remove UNREAD
```

### Calendar Commands

**List events:**
```bash
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:**
```bash
praxis-gws calendar create primary "Meeting Title" \
  --from "2026-02-25T14:00:00" \
  --to "2026-02-25T15:00:00"
```

### Drive Commands

**Search files:**
```bash
praxis-gws drive search "name contains 'project'"
praxis-gws drive search "mimeType = 'application/vnd.google-apps.document'"
```

**Get file metadata:**
```bash
praxis-gws drive get <fileId>
```

## Gmail Search Operators

- `is:unread` - Unread messages
- `is:starred` - Starred messages
- `from:email@example.com` - From specific sender
- `to:email@example.com` - 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:
```bash
npm install -g googleapis
```

---

## 中文说明

# Praxis Google Workspace CLI

适用于 Gmail、日历和云端硬盘的官方 Google API 包装器。直接连接到 Google —— 无第三方代理。

## 设置

### 1. 创建 Google Cloud 项目

1. 前往 https://console.cloud.google.com
2. 创建一个新项目
3. 启用以下 API：
   - Gmail API
   - Google Calendar API
   - Google Drive API

### 2. 创建 OAuth 凭据

1. 前往 **APIs & Services → Credentials**
2. 点击 **Create Credentials → OAuth client ID**
3. 应用类型：**Desktop app**
4. 下载 JSON 文件

### 3. 配置 CLI

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

### 4. 进行身份验证

```bash
praxis-gws gmail labels
```

这将输出一个 Google OAuth URL。在浏览器中打开它，授权应用，然后将授权码粘贴回来。

## 用法

### Gmail 命令

**搜索邮件：**
```bash
praxis-gws gmail search "is:unread from:example.com"
praxis-gws gmail search "subject:meeting has:attachment" --max 20
```

**获取邮件：**
```bash
praxis-gws gmail get <messageId>
```

**发送邮件：**
```bash
praxis-gws gmail send "recipient@example.com" "Subject" "Body text"
```

**创建草稿：**
```bash
praxis-gws gmail draft "recipient@example.com" "Subject" "Draft body"
```

**列出标签：**
```bash
praxis-gws gmail labels
```

**修改标签：**
```bash
praxis-gws gmail modify <messageId> --add STARRED --remove UNREAD
```

### 日历命令

**列出事件：**
```bash
praxis-gws calendar list primary --max 10
praxis-gws calendar list primary --from "2026-02-22T00:00:00" --to "2026-03-01T23:59:59"
```

**创建事件：**
```bash
praxis-gws calendar create primary "Meeting Title" \
  --from "2026-02-25T14:00:00" \
  --to "2026-02-25T15:00:00"
```

### 云端硬盘命令

**搜索文件：**
```bash
praxis-gws drive search "name contains 'project'"
praxis-gws drive search "mimeType = 'application/vnd.google-apps.document'"
```

**获取文件元数据：**
```bash
praxis-gws drive get <fileId>
```

## Gmail 搜索运算符

- `is:unread` - 未读邮件
- `is:starred` - 加星标的邮件
- `from:email@example.com` - 来自特定发件人
- `to:email@example.com` - 发往特定收件人
- `subject:keyword` - 主题包含关键词
- `after:2026/01/01` - 在某日期之后
- `before:2026/12/31` - 在某日期之前
- `has:attachment` - 有附件
- `in:inbox` - 在收件箱中
- `label:important` - 带有特定标签

## 常用标签

- `INBOX` - 收件箱
- `SENT` - 已发送邮件
- `DRAFT` - 草稿
- `STARRED` - 加星标
- `UNREAD` - 未读
- `IMPORTANT` - 重要
- `TRASH` - 垃圾箱
- `SPAM` - 垃圾邮件

## 安全

- OAuth 令牌本地存储在 `~/.config/praxis-gws/`
- 直接连接到 Google 的 API（无代理）
- 使用官方 `googleapis` Node.js 库
- 所需的作用域：
  - `https://www.googleapis.com/auth/gmail.modify`
  - `https://www.googleapis.com/auth/calendar`
  - `https://www.googleapis.com/auth/drive.readonly`

## 故障排除

**错误：credentials.json not found**
→ 运行 `praxis-gws auth credentials /path/to/client_secret.json`

**错误：Invalid grant / Token expired**
→ 删除 `~/.config/praxis-gws/token.json` 并重新运行以触发新的 OAuth 流程

**"Google hasn't verified this app" 警告**
→ 点击 **Advanced → Go to [project name] (unsafe)** 以继续

## CLI 脚本

CLI 位于：
```
scripts/praxis-gws.js
```

需要 Node.js 和 `googleapis` npm 包：
```bash
npm install -g googleapis
```