@cli4ai/gmail 1.0.2 → 1.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +112 -113
- package/c4ai.json +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,65 +1,94 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @cli4ai/gmail
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> Official @cli4ai package • https://cli4ai.com • Install c4ai: `npm i -g c4ai`
|
|
4
|
+
|
|
5
|
+
Full-featured Gmail CLI via Google API. Fast search, send/reply/forward, drafts, attachments, and labels.
|
|
6
|
+
|
|
7
|
+
## Setup
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm i -g c4ai
|
|
11
|
+
c4ai add -g gmail
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
### 1) Google Cloud OAuth
|
|
15
|
+
|
|
16
|
+
1. Go to https://console.cloud.google.com
|
|
17
|
+
2. Create a project (or use an existing one)
|
|
18
|
+
3. Enable the Gmail API
|
|
19
|
+
4. Create OAuth 2.0 credentials (Desktop app recommended)
|
|
20
|
+
5. Download the OAuth client JSON
|
|
21
|
+
|
|
22
|
+
### 2) Point the tool at your credentials
|
|
23
|
+
|
|
24
|
+
Set `GMAIL_CREDENTIALS_PATH` to the downloaded JSON (optional: `GMAIL_TOKEN_PATH`).
|
|
25
|
+
|
|
26
|
+
Example:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
GMAIL_CREDENTIALS_PATH="$HOME/Downloads/credentials.json" c4ai run gmail inbox
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
On first run, the tool prints an authorization URL and prompts for the code, then stores a token at `GMAIL_TOKEN_PATH` (default: `token.json` inside the installed package directory).
|
|
4
33
|
|
|
5
34
|
## Commands
|
|
6
35
|
|
|
7
36
|
### Reading
|
|
8
37
|
```bash
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
38
|
+
c4ai run gmail inbox [limit] # Recent inbox messages (default: 20)
|
|
39
|
+
c4ai run gmail unread [limit] # Unread messages only
|
|
40
|
+
c4ai run gmail search <query> [limit] # Search with Gmail syntax
|
|
41
|
+
c4ai run gmail read <id> # Read full message
|
|
42
|
+
c4ai run gmail thread <id> # Full conversation thread
|
|
43
|
+
c4ai run gmail threads [limit] [query] # List recent threads
|
|
15
44
|
```
|
|
16
45
|
|
|
17
46
|
### Actions
|
|
18
47
|
```bash
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
48
|
+
c4ai run gmail archive <id> # Archive (remove from inbox)
|
|
49
|
+
c4ai run gmail trash <id> # Move to trash
|
|
50
|
+
c4ai run gmail untrash <id> # Restore from trash
|
|
51
|
+
c4ai run gmail star <id> # Star message
|
|
52
|
+
c4ai run gmail unstar <id> # Unstar message
|
|
53
|
+
c4ai run gmail markread <id> # Mark as read
|
|
54
|
+
c4ai run gmail markunread <id> # Mark as unread
|
|
26
55
|
```
|
|
27
56
|
|
|
28
57
|
### Sending
|
|
29
58
|
```bash
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
59
|
+
c4ai run gmail send <to> <subject> <body> # Send new email
|
|
60
|
+
c4ai run gmail reply <id> <body> # Reply to message
|
|
61
|
+
c4ai run gmail replyall <id> <body> # Reply to all
|
|
62
|
+
c4ai run gmail forward <id> <to> [body] # Forward message
|
|
63
|
+
c4ai run gmail draft <to> <subject> <body> # Create draft (legacy)
|
|
35
64
|
```
|
|
36
65
|
|
|
37
66
|
### Drafts
|
|
38
67
|
```bash
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
68
|
+
c4ai run gmail drafts # List all drafts
|
|
69
|
+
c4ai run gmail draft-get <id> # Get draft content
|
|
70
|
+
c4ai run gmail draft-create <to> <subj> <body> # Create new draft
|
|
71
|
+
c4ai run gmail draft-reply <msg-id> <body> # Create draft reply to message
|
|
72
|
+
c4ai run gmail draft-update <id> <to> <s> <b> # Update existing draft
|
|
73
|
+
c4ai run gmail draft-delete <id> # Delete draft
|
|
74
|
+
c4ai run gmail draft-send <id> # Send draft
|
|
46
75
|
```
|
|
47
76
|
|
|
48
77
|
### Attachments
|
|
49
78
|
```bash
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
79
|
+
c4ai run gmail attachments <id> # List attachments in message
|
|
80
|
+
c4ai run gmail download <id> [filename] [out] # Download specific attachment
|
|
81
|
+
c4ai run gmail download-all <id> [dir] # Download all attachments
|
|
53
82
|
```
|
|
54
83
|
|
|
55
84
|
### Labels
|
|
56
85
|
```bash
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
86
|
+
c4ai run gmail labels # List all labels
|
|
87
|
+
c4ai run gmail label <id> <label> # Add label to message
|
|
88
|
+
c4ai run gmail unlabel <id> <label> # Remove label
|
|
89
|
+
c4ai run gmail label-info <label> # Get label with counts
|
|
90
|
+
c4ai run gmail label-create <name> # Create new label
|
|
91
|
+
c4ai run gmail label-delete <name> # Delete label
|
|
63
92
|
```
|
|
64
93
|
|
|
65
94
|
## Output Flags
|
|
@@ -81,130 +110,100 @@ The search command uses Gmail's powerful search syntax:
|
|
|
81
110
|
|
|
82
111
|
```bash
|
|
83
112
|
# By sender/recipient
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
113
|
+
c4ai run gmail search "from:boss@company.com"
|
|
114
|
+
c4ai run gmail search "to:me"
|
|
115
|
+
c4ai run gmail search "cc:team@company.com"
|
|
87
116
|
|
|
88
117
|
# By status
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
118
|
+
c4ai run gmail search "is:unread"
|
|
119
|
+
c4ai run gmail search "is:starred"
|
|
120
|
+
c4ai run gmail search "is:important"
|
|
92
121
|
|
|
93
122
|
# By content
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
123
|
+
c4ai run gmail search "subject:meeting"
|
|
124
|
+
c4ai run gmail search "has:attachment"
|
|
125
|
+
c4ai run gmail search "filename:pdf"
|
|
97
126
|
|
|
98
127
|
# By date
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
128
|
+
c4ai run gmail search "after:2024/12/01"
|
|
129
|
+
c4ai run gmail search "before:2024/12/31"
|
|
130
|
+
c4ai run gmail search "newer_than:7d"
|
|
131
|
+
c4ai run gmail search "older_than:1m"
|
|
103
132
|
|
|
104
133
|
# By label/location
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
134
|
+
c4ai run gmail search "label:work"
|
|
135
|
+
c4ai run gmail search "in:inbox"
|
|
136
|
+
c4ai run gmail search "in:sent"
|
|
108
137
|
|
|
109
138
|
# Combine queries
|
|
110
|
-
|
|
111
|
-
|
|
139
|
+
c4ai run gmail search "from:boss@company.com is:unread newer_than:7d"
|
|
140
|
+
c4ai run gmail search "has:attachment larger:5M"
|
|
112
141
|
```
|
|
113
142
|
|
|
114
143
|
## Examples
|
|
115
144
|
|
|
116
145
|
```bash
|
|
117
146
|
# Quick inbox scan
|
|
118
|
-
|
|
147
|
+
c4ai run gmail inbox 10 --compact
|
|
119
148
|
|
|
120
149
|
# Find unread from specific sender
|
|
121
|
-
|
|
150
|
+
c4ai run gmail search "from:important@client.com is:unread"
|
|
122
151
|
|
|
123
152
|
# Read a specific email
|
|
124
|
-
|
|
153
|
+
c4ai run gmail read 19b176a2f49b681f
|
|
125
154
|
|
|
126
155
|
# View full conversation thread
|
|
127
|
-
|
|
156
|
+
c4ai run gmail thread 19b176a2f49b681f
|
|
128
157
|
|
|
129
158
|
# Send an email
|
|
130
|
-
|
|
159
|
+
c4ai run gmail send "john@example.com" "Meeting tomorrow" "Hi John,\n\nAre we still on for tomorrow?\n\nThanks"
|
|
131
160
|
|
|
132
161
|
# Reply to an email
|
|
133
|
-
|
|
162
|
+
c4ai run gmail reply 19b176a2f49b681f "Thanks for the update, looks good!"
|
|
134
163
|
|
|
135
164
|
# Forward an email
|
|
136
|
-
|
|
165
|
+
c4ai run gmail forward 19b176a2f49b681f "colleague@example.com" "FYI - see below"
|
|
137
166
|
|
|
138
167
|
# Archive old emails
|
|
139
|
-
|
|
168
|
+
c4ai run gmail archive 19b176a2f49b681f
|
|
140
169
|
|
|
141
170
|
# Label management
|
|
142
|
-
|
|
143
|
-
|
|
171
|
+
c4ai run gmail label 19b176a2f49b681f "Work"
|
|
172
|
+
c4ai run gmail label-info "INBOX"
|
|
144
173
|
|
|
145
174
|
# Send with attachment
|
|
146
|
-
|
|
175
|
+
c4ai run gmail send "john@example.com" "Report" "See attached" --attach=./report.pdf
|
|
147
176
|
|
|
148
177
|
# Multiple attachments
|
|
149
|
-
|
|
178
|
+
c4ai run gmail send "john@example.com" "Files" "Here are the files" --attach=./a.pdf --attach=./b.pdf
|
|
150
179
|
|
|
151
180
|
# List and download attachments
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
181
|
+
c4ai run gmail attachments 19b176a2f49b681f
|
|
182
|
+
c4ai run gmail download 19b176a2f49b681f "report.pdf" ./downloads/report.pdf
|
|
183
|
+
c4ai run gmail download-all 19b176a2f49b681f ./downloads/
|
|
155
184
|
|
|
156
185
|
# Draft management
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
## Setup
|
|
164
|
-
|
|
165
|
-
### 1. Google Cloud Project
|
|
166
|
-
|
|
167
|
-
1. Go to [Google Cloud Console](https://console.cloud.google.com)
|
|
168
|
-
2. Create a project (or use existing)
|
|
169
|
-
3. Enable Gmail API
|
|
170
|
-
4. Create OAuth 2.0 credentials (Desktop app type)
|
|
171
|
-
5. Download `credentials.json`
|
|
172
|
-
|
|
173
|
-
### 2. Place Credentials
|
|
174
|
-
|
|
175
|
-
Put `credentials.json` in the `gmail/` directory, or set path in `.env`:
|
|
176
|
-
|
|
177
|
-
```bash
|
|
178
|
-
GMAIL_CREDENTIALS_PATH=/path/to/credentials.json
|
|
179
|
-
GMAIL_TOKEN_PATH=/path/to/token.json
|
|
186
|
+
c4ai run gmail drafts
|
|
187
|
+
c4ai run gmail draft-create "john@example.com" "Draft" "Will finish later"
|
|
188
|
+
c4ai run gmail draft-reply 19b176a2f49b681f "Thanks, need to think about this"
|
|
189
|
+
c4ai run gmail draft-send r123456789
|
|
180
190
|
```
|
|
181
191
|
|
|
182
|
-
### 3. First Run
|
|
183
|
-
|
|
184
|
-
On first run, you'll be prompted to authorize:
|
|
185
|
-
|
|
186
|
-
1. Visit the OAuth URL shown
|
|
187
|
-
2. Sign in with your Google account
|
|
188
|
-
3. Copy the authorization code
|
|
189
|
-
4. Paste it in the terminal
|
|
190
|
-
|
|
191
|
-
Token is saved and auto-refreshes.
|
|
192
|
-
|
|
193
192
|
## Project Structure
|
|
194
193
|
|
|
195
194
|
```
|
|
196
195
|
gmail/
|
|
197
|
-
├── run.
|
|
196
|
+
├── run.ts # CLI entry point
|
|
198
197
|
├── lib/
|
|
199
|
-
│ ├── api.
|
|
200
|
-
│ ├── messages.
|
|
201
|
-
│ ├── threads.
|
|
202
|
-
│ ├── send.
|
|
203
|
-
│ ├── drafts.
|
|
204
|
-
│ ├── attachments.
|
|
205
|
-
│ └── labels.
|
|
206
|
-
├── credentials.json
|
|
207
|
-
└── token.json
|
|
198
|
+
│ ├── api.ts # Gmail API client + OAuth
|
|
199
|
+
│ ├── messages.ts # inbox, unread, search, read, archive...
|
|
200
|
+
│ ├── threads.ts # Thread operations
|
|
201
|
+
│ ├── send.ts # send, reply, forward (with attachment support)
|
|
202
|
+
│ ├── drafts.ts # Draft management, reply drafts
|
|
203
|
+
│ ├── attachments.ts # List, download attachments
|
|
204
|
+
│ └── labels.ts # Label management
|
|
205
|
+
├── credentials.json # OAuth credentials (gitignored)
|
|
206
|
+
└── token.json # Auth token (gitignored)
|
|
208
207
|
```
|
|
209
208
|
|
|
210
209
|
## Required Scopes
|
package/c4ai.json
CHANGED