Google (Personal)

README.md

---
name: Google (Personal)
description: Gmail, Calendar, Drive, Docs, Sheets, YouTube, Tasks, Contacts, and Photos for personal Google accounts (@gmail.com) via OAuth. One-time browser sign-in; token saved in the skill. Use for send/list email, calendar events, Drive files (list/upload/download/delete/move/share), Docs and Sheets (create/read/append), YouTube search/upload, Tasks (list/create/complete), Contacts (list/create), and Photos (list albums/photos, upload). For Workspace use "google-workspace" instead.
credentials:
  - GMAIL_CLIENT_SECRET_JSON
metadata:
  sulala:
    emoji: "📧"
    requires:
      bins:
        - node
---

# Google (Personal) — Gmail, Calendar, Drive, Docs, Sheets, YouTube, Tasks, Contacts, Photos

Use **personal Google** (@gmail.com) with one-time OAuth sign-in. Use the **exec** tool with **skill_id: "google-personal"** so `GMAIL_CLIENT_SECRET_JSON` is injected from skill config. After the first run that opens a browser, `token.json` is saved for reuse.

## When to use

- **Gmail** — Send/list email. See [references/gmail.md](references/gmail.md).
- **Calendar** — Create/list events. See [references/calendar.md](references/calendar.md).
- **Drive** — List, upload, download, delete, move, create folder, get share link. See [references/drive.md](references/drive.md).
- **Docs** — Create, read, append text. See [references/docs.md](references/docs.md).
- **Sheets** — Create, read range, append row. See [references/sheets.md](references/sheets.md).
- **YouTube** — Search videos; upload (youtube_upload.js). See [references/youtube.md](references/youtube.md) if present.
- **Tasks** — List tasks, create task, mark complete. See [references/tasks.md](references/tasks.md).
- **Contacts** — List contacts, create contact. See [references/contacts.md](references/contacts.md).
- **Photos** — List albums, list photos, upload photo. See [references/photos.md](references/photos.md).
- For **Google Workspace** (e.g. @company.com) use the **google-workspace** skill instead.

## Setup

### 1. Create OAuth 2.0 credentials (Google Cloud)

1. Open [Google Cloud Console](https://console.cloud.google.com/) and select or create a project.
2. **APIs & Services** → **Library** → enable **Gmail API**, **Google Calendar API**, **Google Drive API**, **Google Docs API**, **Google Sheets API**, **YouTube Data API v3**, **Google Tasks API**, **People API**, and **Photos Library API** (as needed for the features you use).
3. **APIs & Services** → **Credentials** → **Create credentials** → **OAuth client ID**.
4. If prompted, configure the OAuth consent screen (External, add your email as test user).
5. Application type: **Web application**.
6. Under **Authorized redirect URIs** add: **`http://localhost:8091/`**
7. Create and download the client JSON (or copy the full JSON).

### 2. Configure the skill in the dashboard

1. In the Sulala dashboard, go to **Skills** → find **Google (Personal)** → **Setup**.
2. Paste the full OAuth client JSON into **OAuth client JSON** (the whole object, e.g. `{"web":{"client_id":"...","client_secret":"...","redirect_uris":["http://localhost:8091/"]}}`). Save.

### 3. Install Node dependencies

From the skill directory (e.g. `~/.agent-os/skills/google-personal`):

```bash
npm install
```

Or run via **exec** with `skill_id: "google-personal"` and `command: "npm install"`.

### 4. First sign-in (one time)

Run the send or list script **once** from an environment where a browser can open (e.g. your dev machine, from the skill directory). A browser will open; sign in with your Gmail and allow access. After that, `scripts/token.json` is saved and the agent can send/list and create calendar events without signing in again. If you add Calendar API or scopes later, delete `token.json` and run a script again to re-authorize with the new scopes.

Example (from the machine where the agent runs):

```bash
cd ~/.agent-os/skills/google-personal
export GMAIL_CLIENT_SECRET_JSON='<paste JSON from dashboard>'
node scripts/gmail_send.js 'you@example.com' 'Test' 'Hello'
```

Or run any command that uses the skill with exec; if no token exists, the script will try to open a browser (works only if the process can open a browser on that machine).

---

Scripts read `GMAIL_CLIENT_SECRET_JSON` from the environment (injected by exec when **skill_id** is `google-personal`). Token is stored in `scripts/token.json` in the skill directory.

## Gmail: how to run (use exec with skill_id "google-personal")

- **Send email**: use **exec** with `skill_id: "google-personal"` and command:
  `node scripts/gmail_send.js 'recipient@example.com' 'Subject line' 'Body text'`
- **List messages**: use **exec** with `skill_id: "google-personal"` and command:
  `node scripts/gmail_list.js [max_results] [query]`
  Example: `node scripts/gmail_list.js 10` or `node scripts/gmail_list.js 5 'is:unread'`

## Calendar: how to run (use exec with skill_id "google-personal")

- **Create event**: use **exec** with `skill_id: "google-personal"` and command:
  `node scripts/calendar_create.js 'Summary' 'start_ISO8601' 'end_ISO8601' [description]`
  Example (9 PM today, 1 hour): `node scripts/calendar_create.js 'Go to gym' '2025-03-17T21:00:00Z' '2025-03-17T22:00:00Z'`
  When the user says "9 PM" or "at 5", convert to today's date and that time in ISO 8601 (e.g. 9 PM → 21:00 in the user's timezone or UTC).
- **List events**: use **exec** with `skill_id: "google-personal"` and command:
  `node scripts/calendar_events.js [max_results]`
  Example: `node scripts/calendar_events.js 10`

## Drive: how to run (use exec with skill_id "google-personal")

- **List files**: use **exec** with `skill_id: "google-personal"` and command:
  `node scripts/drive_list.js [folderId] [max_results]` or `node scripts/gdrive_list.js [folderId] [max_results]`
  Example: `node scripts/drive_list.js root 20` or `node scripts/gdrive_list.js root 20`
- **Upload file**: use **exec** with `skill_id: "google-personal"` and command:
  `node scripts/drive_upload.js '<filePath>' [parentFolderId] [driveFileName]`
  Example: `node scripts/drive_upload.js '/Users/saiko/.agent-os/workspaces/google_agent/uploads/screenshot.png' root`
  filePath can be absolute (e.g. workspace uploads path) or relative; parentFolderId defaults to 'root'.
- **Create folder**: `node scripts/drive_create_folder.js 'Folder Name' [parentId]`

## Docs: how to run (use exec with skill_id "google-personal")

- **Create doc**: `node scripts/docs_create.js '<title>' [initialText]`
- **Read doc**: `node scripts/docs_read.js <documentId>`
- **Append text**: `node scripts/docs_append.js <documentId> 'Text to append'`

## Sheets: how to run (use exec with skill_id "google-personal")

- **Create sheet**: `node scripts/sheets_create.js 'Title'`
- **Read range**: `node scripts/sheets_read.js <spreadsheetId> <range>`
- **Append row**: `node scripts/sheets_append.js <spreadsheetId> <range> 'val1' 'val2' ...`

## Tasks: how to run (use exec with skill_id "google-personal")

- **List tasks**: `node scripts/tasks_list.js [tasklistId] [max_results]`
- **Create task**: `node scripts/tasks_create.js 'Title' [tasklistId]`
- **Mark complete**: `node scripts/tasks_complete.js <taskId> [tasklistId]`

## Contacts: how to run (use exec with skill_id "google-personal")

- **List contacts**: `node scripts/contacts_list.js [max_results]`
- **Create contact**: `node scripts/contacts_create.js 'Display Name' 'email@example.com' [phone]`

## Photos: how to run (use exec with skill_id "google-personal")

- **List albums**: `node scripts/photos_albums.js [max_results]`
- **List photos**: `node scripts/photos_list.js [max_results]`
- **Upload photo**: `node scripts/photos_upload.js <filePath> [albumId]`

## Drive extras: how to run (use exec with skill_id "google-personal")

- **Download**: `node scripts/drive_download.js <fileId> [outputPath]`
- **Delete (trash)**: `node scripts/drive_delete.js <fileId>`
- **Move**: `node scripts/drive_move.js <fileId> <targetFolderId>`
- **Share link**: `node scripts/drive_share_link.js <fileId> [reader|writer|commenter]`

All commands must be run with **skill_id: "google-personal"** so the config and token are available.