### Install and Run Go Easy CLI Tools

Source: https://context7.com/marcfargas/go-easy/llms.txt

Install the library as a dependency or execute CLI tools directly using npx without installation.

```bash
# As a library
npm install @marcfargas/go-easy

# As CLI tools (no install needed)
npx go-gmail you@example.com search "is:unread"
npx go-drive you@example.com ls
npx go-calendar you@example.com events primary
npx go-tasks you@example.com lists
```

--------------------------------

### Install go-easy library and CLI tools

Source: https://github.com/marcfargas/go-easy/blob/main/README.md

Use npm to install the library or npx to execute CLI tools directly without installation.

```bash
# As a library
npm install @marcfargas/go-easy

# As CLI tools (no install needed)
npx go-gmail you@example.com search "is:unread"
npx go-drive you@example.com ls
npx go-calendar you@example.com events primary
```

--------------------------------

### Drive Query Syntax Examples

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/drive.md

Examples of using Drive API v3 query syntax with the CLI. Queries must be wrapped in double quotes.

```bash
npx go-drive <account> ls --query="name contains 'report'"
npx go-drive <account> ls --query="mimeType = 'application/pdf' and name contains 'invoice'"
```

--------------------------------

### Go-Easy Development Commands

Source: https://github.com/marcfargas/go-easy/blob/main/README.md

Common development commands for the go-easy project, including installation, building, testing, linting, and watching for changes.

```bash
npm install        # install deps
npm run build      # compile TypeScript
npm test           # run tests (vitest)
npm run lint       # type-check without emitting
npm run dev        # watch mode
```

--------------------------------

### CLI: Create various event types

Source: https://context7.com/marcfargas/go-easy/llms.txt

Examples of creating timed, all-day, attendee-based, working location, out-of-office, and focus time events via the CLI.

```bash
npx go-calendar user@example.com create primary \
  --summary="Team Meeting" \
  --start=2026-02-10T10:00:00+01:00 \
  --end=2026-02-10T11:00:00+01:00 \
  --description="Weekly sync" \
  --location="Conference Room A"
```

```bash
npx go-calendar user@example.com create primary \
  --summary="Company Holiday" \
  --start=2026-02-14 \
  --end=2026-02-15 \
  --all-day
```

```bash
npx go-calendar user@example.com create primary \
  --summary="Project Review" \
  --start=2026-02-12T14:00:00+01:00 \
  --end=2026-02-12T15:00:00+01:00 \
  --attendees=alice@example.com,bob@example.com
```

```bash
npx go-calendar user@example.com create primary \
  --type=workingLocation \
  --summary="Home" \
  --start=2026-02-10 --end=2026-02-11 --all-day \
  --wl-type=homeOffice
```

```bash
npx go-calendar user@example.com create primary \
  --type=outOfOffice \
  --summary="Vacation" \
  --start=2026-02-14T00:00:00+01:00 \
  --end=2026-02-21T00:00:00+01:00 \
  --auto-decline=declineAllConflictingInvitations \
  --decline-message="On vacation, back Feb 21"
```

```bash
npx go-calendar user@example.com create primary \
  --type=focusTime \
  --summary="Deep Work" \
  --start=2026-02-10T09:00:00+01:00 \
  --end=2026-02-10T12:00:00+01:00 \
  --auto-decline=declineOnlyNewConflictingInvitations \
  --chat-status=doNotDisturb
```

--------------------------------

### Initialize and Use Go-Easy Task API

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/tasks.md

Demonstrates how to authenticate with the Go-Easy API and perform various task management operations like listing, creating, updating, completing, and deleting tasks and task lists. Requires prior authentication setup.

```typescript
import { getAuth } from '@marcfargas/go-easy/auth';
import { listTaskLists, listTasks, getTask, createTask,
         updateTask, completeTask, moveTask, deleteTask,
         createTaskList, deleteTaskList, clearCompleted
} from '@marcfargas/go-easy/tasks';
import { setSafetyContext } from '@marcfargas/go-easy';

const auth = await getAuth('tasks', '<account>');

// List task lists
const lists = await listTaskLists(auth);

// List tasks (with pagination)
const page1 = await listTasks(auth, 'listId', { maxResults: 50 });
if (page1.nextPageToken) {
  const page2 = await listTasks(auth, 'listId', {
    maxResults: 50,
    pageToken: page1.nextPageToken,
  });
}

// Get a task
const task = await getTask(auth, 'listId', 'taskId');

// Create a task
const created = await createTask(auth, 'listId', {
  title: 'Buy milk',
  notes: 'Whole milk',
  due: '2026-02-14',
});

// Create a subtask
await createTask(auth, 'listId', {
  title: 'Buy oat milk',
  parent: 'parentTaskId',
});

// Update (PATCH — only provided fields)
await updateTask(auth, 'listId', 'taskId', { title: 'Updated' });

// Complete
await completeTask(auth, 'listId', 'taskId');

// Move (reparent or reorder)
await moveTask(auth, 'listId', 'taskId', { parent: 'newParentId' });

// Destructive — needs safety context
setSafetyContext({ confirm: async (op) => { /* ... */ return true; } });
await deleteTask(auth, 'listId', 'taskId');
await deleteTaskList(auth, 'listId');
await clearCompleted(auth, 'listId');
```

--------------------------------

### Initiate account authorization

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/SKILL.md

Start the process of adding or upgrading a Google account. This command returns an authorization URL that the user must visit to grant permissions. Polling with the same command is required to check the status.

```bash
# Phase 1: Start — returns auth URL immediately
npx go-easy auth add marc@blegal.eu
# → { "status": "started", "authUrl": "https://accounts.google.com/...", "expiresIn": 300 }
```

```bash
# Phase 2: Poll — same command, returns current status
npx go-easy auth add marc@blegal.eu
# → { "status": "waiting", "authUrl": "...", "expiresIn": 245 }
# → { "status": "complete", "email": "marc@blegal.eu", "scopes": ["gmail", "drive", "calendar", "tasks"] }
```

--------------------------------

### Execute service CLI commands

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/SKILL.md

Examples of using individual service CLIs to perform operations on Gmail, Drive, Calendar, and Tasks.

```bash
npx go-gmail user@example.com search "is:unread"
npx go-drive user@example.com ls
npx go-calendar user@example.com events primary
npx go-tasks user@example.com lists
```

--------------------------------

### GET lists

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/tasks.md

List all task lists associated with the account.

```APIDOC
## GET lists

### Description
List all task lists for the specified account.

### Method
GET

### Endpoint
npx go-tasks <account> lists

### Response
#### Success Response (200)
- **Array<TaskList>** - A list of task list objects.
```

--------------------------------

### Gmail SDK Operations

Source: https://context7.com/marcfargas/go-easy/llms.txt

TypeScript examples for managing Gmail drafts, labels, and attachments.

```typescript
import { getAuth } from '@marcfargas/go-easy/auth';
import { createDraft, listDrafts, sendDraft } from '@marcfargas/go-easy/gmail';
import { setSafetyContext } from '@marcfargas/go-easy';

const auth = await getAuth('gmail', 'user@example.com');

// Create a draft (WRITE - no safety gate)
const draft = await createDraft(auth, {
  to: 'recipient@example.com',
  subject: 'Draft Email',
  body: 'This is a draft.',
  cc: 'team@example.com',
});
console.log(draft.id); // Draft ID

// Create reply draft (will be placed in original thread)
const replyDraft = await createDraft(auth, {
  to: 'sender@example.com',
  subject: 'RE: Original Subject',
  body: 'Reply content',
  threadId: 'THREAD_ID',
  extraHeaders: {
    'In-Reply-To': '<original@mail.gmail.com>',
    'References': '<original@mail.gmail.com>',
  },
});

// List drafts with pagination
const drafts = await listDrafts(auth, 10);
if (drafts.nextPageToken) {
  const moreDrafts = await listDrafts(auth, 10, drafts.nextPageToken);
}

// Send draft (DESTRUCTIVE)
setSafetyContext({ confirm: async () => true });
const sent = await sendDraft(auth, draft.id);
```

```typescript
import { getAuth } from '@marcfargas/go-easy/auth';
import { listLabels, batchModifyLabels } from '@marcfargas/go-easy/gmail';

const auth = await getAuth('gmail', 'user@example.com');

// List labels
const labels = await listLabels(auth);
// → [{ id: 'INBOX', name: 'INBOX', type: 'system' }, ...]
const followUpLabel = labels.find(l => l.name === 'Follow Up');

// Batch modify labels (WRITE - no safety gate)
await batchModifyLabels(auth, {
  messageIds: ['MSG1', 'MSG2', 'MSG3'],
  addLabelIds: [followUpLabel?.id || 'Label_42'],
  removeLabelIds: ['UNREAD'],
});
```

```typescript
import { getAuth } from '@marcfargas/go-easy/auth';
import { getMessage, getAttachmentContent } from '@marcfargas/go-easy/gmail';
import * as fs from 'fs';

const auth = await getAuth('gmail', 'user@example.com');

// Get message with attachment info
const msg = await getMessage(auth, 'MSG_ID123');
const attachment = msg.attachments[0];

// Download attachment as Buffer
const content = await getAttachmentContent(auth, msg.id, attachment.id);
fs.writeFileSync(attachment.filename, content);
console.log(`Saved ${attachment.filename} (${content.length} bytes)`);
```

--------------------------------

### Drive Query Combination

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/drive.md

Example of combining query conditions using logical operators.

```text
name contains 'report' and mimeType = 'application/pdf'
```

--------------------------------

### Forward Emails via CLI

Source: https://context7.com/marcfargas/go-easy/llms.txt

Forward emails using the CLI, with options to save as a draft, add a note, filter attachments, send immediately, or start a new thread.

```bash
# CLI: Forward as draft (WRITE - no confirmation needed)
npx go-gmail user@example.com forward MSG_ID123 --to=colleague@example.com
# → { "ok": true, "id": "DRAFT_ID", "threadId": "..." }

# CLI: Forward with note above forwarded content
echo "FYI - please review this." > note.txt
npx go-gmail user@example.com forward MSG_ID123 \
  --to=colleague@example.com \
  --body-text-file=note.txt

# CLI: Forward with attachment filtering
npx go-gmail user@example.com forward MSG_ID123 \
  --to=colleague@example.com \
  --exclude=Receipt,Invoice  # Exclude attachments containing these names
npx go-gmail user@example.com forward MSG_ID123 \
  --to=colleague@example.com \
  --include=Contract         # Only include attachments containing "Contract"

# CLI: Forward and send immediately (DESTRUCTIVE)
npx go-gmail user@example.com forward MSG_ID123 \
  --to=colleague@example.com \
  --send-now \
  --confirm
# → { "ok": true, "id": "SENT_MSG_ID", "threadId": "..." }

# CLI: Forward to new thread
npx go-gmail user@example.com forward MSG_ID123 \
  --to=colleague@example.com \
  --no-thread
```

--------------------------------

### Get Single Email Message (TypeScript)

Source: https://context7.com/marcfargas/go-easy/llms.txt

Retrieve a single email message using TypeScript. This example shows how to get structured message data, the raw RFC 2822 format, and how to sanitize HTML content.

```typescript
import { getAuth } from '@marcfargas/go-easy/auth';
import { getMessage, getMessageRaw, sanitizeEmailHtml } from '@marcfargas/go-easy/gmail';
import * as fs from 'fs';

const auth = await getAuth('gmail', 'user@example.com');

// Get structured message
const msg = await getMessage(auth, 'MSG_ID123');
console.log(msg.from);         // "sender@example.com"
console.log(msg.subject);      // "Re: Project Update"
console.log(msg.body.text);    // Plain text body
console.log(msg.body.html);    // HTML body (if present)
console.log(msg.attachments);  // [{ id, filename, mimeType, size }]

// Get raw RFC 2822 message (works for embedded message/rfc822 attachments)
const raw: Buffer = await getMessageRaw(auth, 'MSG_ID123');
fs.writeFileSync('message.eml', raw);

// Sanitize HTML for safe rendering
const safeHtml = sanitizeEmailHtml(msg.body.html || '');
// Strips <script>, <iframe>, onclick, javascript: hrefs, data: images
```

--------------------------------

### Get Email Thread (TypeScript)

Source: https://context7.com/marcfargas/go-easy/llms.txt

Retrieve an email thread using TypeScript. This example demonstrates fetching the thread with all its messages and exporting the thread as an mbox file.

```typescript
import { getAuth } from '@marcfargas/go-easy/auth';
import { getThread, getThreadMbox } from '@marcfargas/go-easy/gmail';
import * as fs from 'fs';

const auth = await getAuth('gmail', 'user@example.com');

// Get thread with all messages
const thread = await getThread(auth, 'THREAD_ID123');
console.log(thread.messages.length); // Number of messages in thread
thread.messages.forEach(msg => {
  console.log(`${msg.from}: ${msg.subject}`);
});

// Export thread as mbox (RFC 2822 format, compatible with Thunderbird/mutt)
const mbox: Buffer = await getThreadMbox(auth, 'THREAD_ID123', 'me@example.com');
fs.writeFileSync('thread.mbox', mbox);
```

--------------------------------

### Use go-easy TypeScript library

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/calendar.md

Demonstrates authentication, listing, creating, updating, and deleting events, as well as checking free/busy status programmatically.

```typescript
import { getAuth } from '@marcfargas/go-easy/auth';
import { listCalendars, listEvents, getEvent, createEvent,
         updateEvent, deleteEvent, queryFreeBusy
} from '@marcfargas/go-easy/calendar';
import { setSafetyContext } from '@marcfargas/go-easy';

const auth = await getAuth('calendar', '<account>');

// List calendars
const cals = await listCalendars(auth);

// List events (with pagination)
const page1 = await listEvents(auth, 'primary', {
  timeMin: '2026-02-01T00:00:00Z',
  timeMax: '2026-02-28T23:59:59Z',
  maxResults: 50,
});
if (page1.nextPageToken) {
  const page2 = await listEvents(auth, 'primary', {
    timeMin: '2026-02-01T00:00:00Z',
    timeMax: '2026-02-28T23:59:59Z',
    maxResults: 50,
    pageToken: page1.nextPageToken,
  });
}

// Get single event
const event = await getEvent(auth, 'primary', 'eventId');

// Create event (WRITE — no safety gate)
const created = await createEvent(auth, 'primary', {
  summary: 'Meeting',
  start: '2026-02-10T10:00:00+01:00',
  end: '2026-02-10T11:00:00+01:00',
  timeZone: 'Europe/Madrid',
  location: 'Office',
  attendees: ['alice@example.com'],
});

// Update event (WRITE — PATCH semantics)
await updateEvent(auth, 'primary', 'eventId', {
  summary: 'Updated',
  start: '2026-02-10T11:00:00+01:00',
  end: '2026-02-10T12:00:00+01:00',
});

// Delete event (DESTRUCTIVE — needs safety context)
setSafetyContext({ confirm: async (op) => { /* ... */ return true; } });
await deleteEvent(auth, 'primary', 'eventId');

// Free/busy
const availability = await queryFreeBusy(
  auth,
  ['primary', 'colleague@example.com'],
  '2026-02-10T08:00:00Z',
  '2026-02-10T18:00:00Z'
);
```

--------------------------------

### List Files with Pagination and Ordering (CLI)

Source: https://context7.com/marcfargas/go-easy/llms.txt

Use the CLI to list files with options for maximum results, page tokens for pagination, and ordering by name or creation time.

```bash
npx go-drive user@example.com ls --max=50 --page-token=TOKEN
```

```bash
npx go-drive user@example.com ls --order="name"
```

```bash
npx go-drive user@example.com ls --order="createdTime desc"
```

--------------------------------

### Get Email Thread (CLI)

Source: https://context7.com/marcfargas/go-easy/llms.txt

Retrieve an entire email conversation thread using the CLI. Options include getting the thread as JSON, downloading it as an mbox file, or getting the mbox content as base64 encoded JSON.

```bash
# CLI: Get thread as JSON
npx go-gmail user@example.com thread THREAD_ID123
# → { "id": "...", "snippet": "...", "messages": [GmailMessage, ...] }
```

```bash
# CLI: Download thread as mbox file
npx go-gmail user@example.com thread THREAD_ID123 --format=mbox --output=conversation.mbox
# → { "ok": true, "format": "mbox", "path": "conversation.mbox", "bytes": 45678 }
```

```bash
# CLI: Get mbox as base64 JSON
npx go-gmail user@example.com thread THREAD_ID123 --format=mbox --b64encode
```

--------------------------------

### POST /api/users

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/gmail.md

Get a single message by ID.

```APIDOC
## GET /get

### Description
Get a single message by ID.

### Method
GET

### Endpoint
`npx go-gmail <account> get <messageId> [--format=<format>] [--output=<path>] [--b64encode]`

### Parameters
#### Path Parameters
- **messageId** (string) - Required - The ID of the message to retrieve.

#### Query Parameters
- **format** (string) - Optional - The desired output format. Options: `text`, `html`, `sane-html`, `eml` (default: JSON `GmailMessage`).
- **output** (string) - Optional - Path to write the output file.
- **b64encode** (boolean) - Optional - Encode the output as base64 in JSON.

### Response
#### Success Response (200)
- **format** (string) - The format of the returned data.
- **data** (string) - Base64 encoded data (if `--b64encode` is used).
- **path** (string) - Path to the saved file (if `--output` is used).
- **bytes** (integer) - Size of the output in bytes.
- (Default) **GmailMessage** (object) - Structured JSON representation of the email.

### Response Example (JSON)
```json
{
  "format": "text",
  "data": "PGhlbGxvPjwvaGVsbG8+",
  "bytes": 1234
}
```

### Response Example (Plain Text Body)
```
Hello world!
```

### Response Example (Sanitized HTML Body)
```html
<p>Hello world!</p>
```

### Response Example (Raw EML)
```eml
From: sender@example.com
To: recipient@example.com
Subject: Test Email

This is the email body.
```
```

--------------------------------

### POST /api/users

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/gmail.md

Get authenticated account info.

```APIDOC
## GET /profile

### Description
Get authenticated account info.

### Method
GET

### Endpoint
`npx go-gmail <account> profile`

### Response
#### Success Response (200)
- **email** (string) - The email address of the authenticated account.

### Response Example
```json
{
  "email": "marc@blegal.eu"
}
```
```

--------------------------------

### List Available Accounts

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/tasks.md

Command to list all configured accounts for the Go-Easy CLI. Use this to verify your accounts before performing operations.

```bash
npx go-easy auth list
```

--------------------------------

### POST /api/users

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/gmail.md

Get a full thread (conversation) by ID.

```APIDOC
## GET /thread

### Description
Get a full thread (conversation) by ID.

### Method
GET

### Endpoint
`npx go-gmail <account> thread <threadId> [--format=<format>] [--output=<path>] [--b64encode]`

### Parameters
#### Path Parameters
- **threadId** (string) - Required - The ID of the thread to retrieve.

#### Query Parameters
- **format** (string) - Optional - The desired output format. Options: `mbox` (default: JSON `GmailThread`).
- **output** (string) - Optional - Path to write the output file.
- **b64encode** (boolean) - Optional - Encode the output as base64 in JSON.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success.
- **format** (string) - The format of the returned data (e.g., `mbox`).
- **path** (string) - Path to the saved file (if `--output` is used).
- **bytes** (integer) - Size of the output in bytes.
- **data** (string) - Base64 encoded data (if `--b64encode` is used).
- (Default) **GmailThread** (object) - Structured JSON representation of the thread.

### Response Example (Mbox File)
```mbox
From sender1 date1
Subject: Re: Thread Subject

Message 1 content...

From sender2 date2
Subject: Re: Thread Subject

Message 2 content...
```

### Response Example (JSON Output)
```json
{
  "ok": true,
  "format": "mbox",
  "path": "thread.mbox",
  "bytes": 12483
}
```
```

--------------------------------

### Upload Files and Create Folders (CLI)

Source: https://context7.com/marcfargas/go-easy/llms.txt

Upload local files to Google Drive or create new folders using the CLI. Options include specifying the target folder, custom file names, and parent folders for subfolders.

```bash
# CLI: Upload file to root
npx go-drive user@example.com upload ./report.pdf
# → { "ok": true, "id": "NEW_FILE_ID", "name": "report.pdf", "webViewLink": "..." }

# CLI: Upload to specific folder
npx go-drive user@example.com upload ./report.pdf --folder=FOLDER_ID123

# CLI: Upload with custom name
npx go-drive user@example.com upload ./report.pdf --name="Q1 Report 2026.pdf"

# CLI: Create folder
npx go-drive user@example.com mkdir "New Folder"
# → { "ok": true, "id": "FOLDER_ID", "name": "New Folder", "webViewLink": "..." }

# CLI: Create subfolder
npx go-drive user@example.com mkdir "Subfolder" --parent=PARENT_FOLDER_ID
```

--------------------------------

### Get a Single Message

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/gmail.md

Retrieve a specific email message by its ID.

```typescript
import { getMessage } from '@marcfargas/go-easy/gmail';

const msg = await getMessage(auth, 'messageId');
```

--------------------------------

### Create Folders

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/drive.md

Creates a new folder in Google Drive.

```bash
npx go-drive <account> mkdir "New Folder"
npx go-drive <account> mkdir "Subfolder" --parent=<folderId>
```

--------------------------------

### Get File Metadata

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/drive.md

Retrieves metadata for a specific file by its ID.

```bash
npx go-drive <account> get <fileId>
```

--------------------------------

### Get Single Event

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/calendar.md

Retrieve details for a specific event by its ID.

```bash
npx go-calendar <account> event <calendarId> <eventId>
```

--------------------------------

### List configured accounts

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/SKILL.md

Check which Google accounts are currently configured for go-easy. This command returns a JSON object listing all accounts and their associated scopes.

```bash
npx go-easy auth list
# → { "accounts": [{ "email": "marc@blegal.eu", "scopes": [...], "source": "combined" }] }
```

--------------------------------

### Get a Thread

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/gmail.md

Retrieve an entire email conversation thread by its thread ID.

```typescript
import { getThread } from '@marcfargas/go-easy/gmail';

const thread = await getThread(auth, 'threadId');
```

--------------------------------

### Development Commands

Source: https://github.com/marcfargas/go-easy/blob/main/README.md

Common commands for developing and testing the go-easy library.

```APIDOC
## Development Commands

- **`npm install`**: Install dependencies.
- **`npm run build`**: Compile TypeScript.
- **`npm test`**: Run tests (vitest).
- **`npm run lint`**: Type-check without emitting.
- **`npm run dev`**: Watch mode.
```

--------------------------------

### Gateway CLI Usage

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/calendar.md

General syntax for executing the go-calendar CLI tool.

```bash
npx go-calendar <account> <command> [args...] [--flags]
```

--------------------------------

### CLI Error Responses

Source: https://context7.com/marcfargas/go-easy/llms.txt

Example output for CLI errors and safety-blocked operations.

```bash
# CLI error responses (stderr, exit code 1)
# → { "error": "AUTH_NO_ACCOUNT", "message": "Account \"x@y.com\" not configured", "fix": "npx go-easy auth add x@y.com" }
# → { "error": "NOT_FOUND", "message": "message not found: abc123" }
# → { "error": "QUOTA_EXCEEDED", "message": "Rate limit exceeded" }

# Safety blocked (exit code 2)
# → { "blocked": true, "operation": "gmail.send", "description": "...", "hint": "Add --confirm" }
```

--------------------------------

### GET /freebusy

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/calendar.md

Checks availability across one or more calendars for a specified time range.

```APIDOC
## GET /freebusy

### Description
Retrieves busy time slots for the specified calendars.

### Parameters
#### Path Parameters
- **account** (string) - Required - The account identifier.
- **calendarIds** (string) - Required - Comma-separated list of calendar IDs.

#### Query Parameters
- **from** (string) - Required - Start of the time range (ISO 8601).
- **to** (string) - Required - End of the time range (ISO 8601).

### Response
#### Success Response (200)
- **Array** (object) - List of calendars with their busy slots: `{ calendarId, busy: [{ start, end }] }`
```

--------------------------------

### Importing Go-Easy Modules

Source: https://github.com/marcfargas/go-easy/blob/main/README.md

Demonstrates how to import specific modules from the go-easy library using subpath exports. This allows for more granular control over dependencies.

```typescript
import { getAuth } from '@marcfargas/go-easy/auth';
import { search, send } from '@marcfargas/go-easy/gmail';
import { listFiles, uploadFile } from '@marcfargas/go-easy/drive';
import { listEvents, createEvent } from '@marcfargas/go-easy/calendar';
import { setSafetyContext } from '@marcfargas/go-easy';
```

--------------------------------

### Authenticate a user

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/SKILL.md

Adds a user account to the go-easy configuration, requiring interactive authentication via a URL.

```bash
npx go-easy auth add user@example.com
```

--------------------------------

### Get Single Event

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/calendar.md

Retrieves a specific event by its calendar ID and event ID.

```APIDOC
## Get Single Event

### Description
Retrieves a single event by its unique calendar ID and event ID.

### Method
CLI Command

### Endpoint
`npx go-calendar <account> event <calendarId> <eventId>`

### Parameters
#### Path Parameters
- **account** (string) - Required - The account identifier.
- **calendarId** (string) - Required - The ID of the calendar containing the event.
- **eventId** (string) - Required - The ID of the event to retrieve.

### Returns
`CalendarEvent`

**Note**: For recurring events, this returns the recurring event definition, not individual instances. Use `recurringEventId` from a listed instance to find its parent.
```

--------------------------------

### Manage Authentication with go-easy

Source: https://github.com/marcfargas/go-easy/blob/main/CHANGELOG.md

Commands for managing OAuth2 accounts and scopes. Requires re-authentication for existing accounts after the 0.2.0 update.

```bash
npx go-easy auth add <email>
```

```bash
npx go-easy auth list
```

```bash
npx go-easy auth remove <email> --confirm
```

--------------------------------

### GET tasks

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/tasks.md

List tasks within a specific task list with support for pagination and filtering.

```APIDOC
## GET tasks

### Description
Retrieve tasks from a specific task list.

### Method
GET

### Endpoint
npx go-tasks <account> tasks <listId>

### Parameters
#### Path Parameters
- **account** (string) - Required - The account identifier.
- **listId** (string) - Required - The ID of the task list.

#### Query Parameters
- **max** (number) - Optional - Limit results (default: 20).
- **page-token** (string) - Optional - Token for pagination.
- **show-hidden** (boolean) - Optional - Include completed and cleared tasks.

### Response
#### Success Response (200)
- **items** (Array<Task>) - List of tasks.
- **nextPageToken** (string) - Token for the next page of results.
```

--------------------------------

### Authenticate and manage accounts via CLI

Source: https://github.com/marcfargas/go-easy/blob/main/README.md

Use the CLI to add, list, or remove Google accounts. The add command uses a two-phase flow compatible with AI agents.

```bash
npx go-easy auth add you@example.com
# → { "status": "started", "authUrl": "https://accounts.google.com/..." }
# Open the URL, authorize, then poll:
npx go-easy auth add you@example.com
# → { "status": "complete", "email": "you@example.com", "scopes": ["gmail", "drive", "calendar"] }
```

```bash
npx go-easy auth list                         # List configured accounts
npx go-easy auth add you@example.com          # Add or upgrade account
npx go-easy auth remove you@example.com --confirm  # Remove account
```

--------------------------------

### Handle Unconfirmed Send Request

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/gmail.md

Example of the JSON response when a send operation is blocked due to missing confirmation.

```json
{ "blocked": true, "operation": "gmail.send", "description": "...", "hint": "Add --confirm to execute" }
```

--------------------------------

### Initialize Library and Safety Context

Source: https://context7.com/marcfargas/go-easy/llms.txt

Set up the safety context for destructive operations and retrieve authentication clients for Google services.

```typescript
import { getAuth } from '@marcfargas/go-easy/auth';
import { search, getMessage, send } from '@marcfargas/go-easy/gmail';
import { listFiles, uploadFile } from '@marcfargas/go-easy/drive';
import { listEvents, createEvent } from '@marcfargas/go-easy/calendar';
import { listTaskLists, createTask } from '@marcfargas/go-easy/tasks';
import { setSafetyContext } from '@marcfargas/go-easy';

// Set up safety context (required for destructive operations)
setSafetyContext({
  confirm: async (op) => {
    console.log(`⚠️ ${op.description}`);
    return true; // or prompt user for confirmation
  },
});

// Get auth clients for each service
const gmailAuth = await getAuth('gmail', 'user@example.com');
const driveAuth = await getAuth('drive', 'user@example.com');
const calendarAuth = await getAuth('calendar', 'user@example.com');
const tasksAuth = await getAuth('tasks', 'user@example.com');

// Use the APIs
const emails = await search(gmailAuth, { query: 'is:unread from:client' });
console.log(emails.items); // GmailMessage[]

const files = await listFiles(driveAuth, { maxResults: 10 });
console.log(files.items); // DriveFile[]

const events = await listEvents(calendarAuth, 'primary', { maxResults: 10 });
console.log(events.items); // CalendarEvent[]

const taskLists = await listTaskLists(tasksAuth);
console.log(taskLists); // TaskList[]
```

--------------------------------

### Get Attachment Content

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/gmail.md

Download the content of a specific attachment from an email message. Returns a Buffer containing the attachment data.

```typescript
import { getAttachmentContent } from '@marcfargas/go-easy/gmail';

const content = await getAttachmentContent(auth, 'msgId', 'attId');
// content is a Buffer
```

--------------------------------

### Module Structure and Imports

Source: https://github.com/marcfargas/go-easy/blob/main/README.md

Details on how to import specific modules from the go-easy library using subpath exports.

```APIDOC
## Module Structure

go-easy uses **subpath exports** — import only what you need:

```ts
import { getAuth } from '@marcfargas/go-easy/auth';
import { search, send } from '@marcfargas/go-easy/gmail';
import { listFiles, uploadFile } from '@marcfargas/go-easy/drive';
import { listEvents, createEvent } from '@marcfargas/go-easy/calendar';
import { setSafetyContext } from '@marcfargas/go-easy';
```

### Import Paths

- **`@marcfargas/go-easy`**: Safety context, errors, plus `gmail`/`drive`/`calendar` as namespaces.
- **`@marcfargas/go-easy/auth`**: `getAuth`, `listAccounts`, `listAllAccounts`, `clearAuthCache`.
- **`@marcfargas/go-easy/auth-store`**: `readAccountStore`, `writeAccountStore`, `findAccount`, etc.
- **`@marcfargas/go-easy/scopes`**: `SCOPES`, `ALL_SCOPES`, `scopeToService`.
- **`@marcfargas/go-easy/gmail`**: All Gmail operations.
- **`@marcfargas/go-easy/drive`**: All Drive operations.
- **`@marcfargas/go-easy/calendar`**: All Calendar operations.
```

--------------------------------

### Get Authenticated Account Info

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/gmail.md

Retrieves details about the currently authenticated Gmail account. This is useful for verifying account configuration.

```bash
npx go-gmail <account> profile
# → { "email": "marc@blegal.eu" }
```

--------------------------------

### POST add

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/tasks.md

Create a new task in a specified list.

```APIDOC
## POST add

### Description
Create a new task.

### Method
POST

### Endpoint
npx go-tasks <account> add <listId>

### Parameters
#### Request Body
- **title** (string) - Required - Task title.
- **notes** (string) - Optional - Task description.
- **due** (string) - Optional - Due date (YYYY-MM-DD or RFC 3339).
- **parent** (string) - Optional - ID of parent task for subtasks.
- **previous** (string) - Optional - ID of sibling task to insert after.

### Response
#### Success Response (200)
- **ok** (boolean) - Operation status.
- **id** (string) - The ID of the created task.
```

--------------------------------

### Get a Single Task

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/tasks.md

Fetches a specific task by its ID within a given list. Returns a single Task object.

```bash
npx go-tasks <account> get <listId> <taskId>
```

--------------------------------

### Gateway CLI Usage

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/drive.md

General syntax for executing commands via the go-drive CLI.

```bash
npx go-drive <account> <command> [args...] [--flags]
```

--------------------------------

### Download and Export Files (CLI)

Source: https://context7.com/marcfargas/go-easy/llms.txt

Download binary files or export Google Workspace files to various standard formats using the CLI. Specify target paths for downloads and exports.

```bash
# CLI: Download file to current directory
npx go-drive user@example.com download FILE_ID123
# → { "ok": true, "path": "./filename.pdf", "size": 12345, "mimeType": "application/pdf" }

# CLI: Download to specific path
npx go-drive user@example.com download FILE_ID123 "$TEMP/downloaded.pdf"

# CLI: Export Google Doc to PDF
npx go-drive user@example.com export DOC_ID123 pdf
# → { "ok": true, "path": "./document.pdf", "size": 45678 }

# CLI: Export Google Sheet to Excel
npx go-drive user@example.com export SHEET_ID123 xlsx ./spreadsheet.xlsx

# CLI: Export Google Slides to PDF
npx go-drive user@example.com export SLIDES_ID123 pdf ./presentation.pdf
```

--------------------------------

### Manage Authentication via CLI

Source: https://context7.com/marcfargas/go-easy/llms.txt

Configure OAuth2 credentials and manage user accounts using the CLI authentication flow.

```bash
# Prerequisites: Create credentials.json at ~/.go-easy/
cat ~/.go-easy/credentials.json
# { "clientId": "YOUR_CLIENT_ID.apps.googleusercontent.com", "clientSecret": "YOUR_CLIENT_SECRET" }

# Phase 1: Start auth flow - returns URL immediately
npx go-easy auth add user@example.com
# → { "status": "started", "authUrl": "https://accounts.google.com/...", "expiresIn": 300 }

# Phase 2: Poll for completion (after user clicks URL)
npx go-easy auth add user@example.com
# → { "status": "waiting", "authUrl": "...", "expiresIn": 245 }
# → { "status": "complete", "email": "user@example.com", "scopes": ["gmail", "drive", "calendar", "tasks"] }

# List configured accounts
npx go-easy auth list
# → { "accounts": [{ "email": "user@example.com", "scopes": [...], "source": "combined" }] }

# Remove an account (DESTRUCTIVE)
npx go-easy auth remove user@example.com --confirm
# → { "ok": true, "removed": "user@example.com" }
```

--------------------------------

### POST /update

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/calendar.md

Updates an existing calendar event. Note that summary, start, and end fields are required even for partial updates.

```APIDOC
## POST /update

### Description
Updates an existing event in the specified calendar.

### Parameters
#### Path Parameters
- **account** (string) - Required - The account identifier.
- **eventId** (string) - Required - The ID of the event to update.

#### Request Body (Flags)
- **summary** (string) - Required - Event title.
- **start** (string) - Required - Start time in ISO 8601 format.
- **end** (string) - Required - End time in ISO 8601 format.
- **attendees** (string) - Optional - Comma-separated list of email addresses.
- **description** (string) - Optional - Event description.
- **location** (string) - Optional - Event location.
- **tz** (string) - Optional - IANA timezone.
- **all-day** (boolean) - Optional - Flag for all-day events.

### Response
#### Success Response (200)
- **ok** (boolean) - Status of the operation.
- **id** (string) - The event ID.
- **htmlLink** (string) - Optional - Link to the event.
```

--------------------------------

### Create a New Task List

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/tasks.md

Creates a new, empty task list for the specified account. Returns the ID of the newly created list.

```bash
npx go-tasks <account> create-list --title="Shopping"
```

--------------------------------

### Add an authentication account

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/drive.md

Registers a new account using the specified email address.

```bash
npx go-easy auth add <email>
```

--------------------------------

### Gmail Search Query Syntax Examples

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/gmail.md

Illustrates common Gmail search operators for filtering emails by sender, recipient, subject, status, date, and labels.

```plaintext
- `from:user@example.com` — from sender
- `to:user@example.com` — to recipient
- `subject:invoice` — subject contains
- `is:unread` — unread messages
- `is:starred` — starred
- `has:attachment` — has attachments
- `after:2026/01/01` — after date
- `before:2026/02/01` — before date
- `label:important` — with label
- `in:inbox` — in inbox
- `filename:pdf` — attachment filename
```

```plaintext
Combine with spaces (AND) or `OR`:
```
from:client subject:invoice after:2026/01/01
from:alice OR from:bob
```
```

--------------------------------

### List All Task Lists

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/tasks.md

Use this command to retrieve all task lists associated with a given account. It returns a bare Array<TaskList>.

```bash
npx go-tasks <account> lists
```

--------------------------------

### Gateway CLI Usage

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/gmail.md

The main command structure for the go-gmail CLI. Use this to understand the basic syntax for invoking commands and their arguments.

```bash
npx go-gmail <account> <command> [args...] [--flags]
```

--------------------------------

### Update calendar event via CLI

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/calendar.md

Updates an existing event using the npx go-calendar command. Note that summary, start, and end flags are mandatory.

```bash
npx go-calendar <account> update primary <eventId> \
  --summary="Review" \
  --start=2026-02-10T14:00:00+01:00 \
  --end=2026-02-10T15:00:00+01:00 \
  --attendees=alice@example.com,bob@example.com,carol@example.com
```

--------------------------------

### Get Raw Message Content

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/gmail.md

Retrieve the full, raw RFC 2822 formatted content of an email message. Useful for messages with complex attachments or when standard parsing fails.

```typescript
import { getMessageRaw } from '@marcfargas/go-easy/gmail';
import * as fs from 'fs';

const raw: Buffer = await getMessageRaw(auth, 'msgId');
fs.writeFileSync('message.eml', raw);
```

--------------------------------

### List Files with Pagination and Ordering (TypeScript)

Source: https://context7.com/marcfargas/go-easy/llms.txt

Use the TypeScript API to list files, including handling pagination with `nextPageToken` and applying metadata queries.

```typescript
import { getAuth } from '@marcfargas/go-easy/auth';
import { listFiles } from '@marcfargas/go-easy/drive';

const auth = await getAuth('drive', 'user@example.com');

// List root folder
const root = await listFiles(auth, { maxResults: 20 });
console.log(root.items);
// → [{ id, name, mimeType, size, createdTime, modifiedTime, webViewLink, ... }]

// List specific folder with pagination
const page1 = await listFiles(auth, { folderId: 'FOLDER_ID', maxResults: 50 });
if (page1.nextPageToken) {
  const page2 = await listFiles(auth, {
    folderId: 'FOLDER_ID',
    maxResults: 50,
    pageToken: page1.nextPageToken,
  });
}

// List with metadata query
const pdfs = await listFiles(auth, {
  query: "mimeType = 'application/pdf' and name contains 'invoice'",
  maxResults: 10,
});
```

--------------------------------

### Use go-easy in TypeScript

Source: https://github.com/marcfargas/go-easy/blob/main/README.md

Demonstrates authenticating, searching Gmail, and performing a destructive send operation with a safety context.

```typescript
import { getAuth } from '@marcfargas/go-easy/auth';
import { search, send } from '@marcfargas/go-easy/gmail';
import { setSafetyContext } from '@marcfargas/go-easy';

const auth = await getAuth('gmail', 'you@example.com');

// Search (READ — no safety gate)
const results = await search(auth, { query: 'is:unread from:client' });
console.log(results.items);

// Send (DESTRUCTIVE — requires safety context)
setSafetyContext({
  confirm: async (op) => {
    console.log(`⚠️ ${op.description}`);
    return true; // or prompt the user
  },
});

await send(auth, {
  to: 'client@example.com',
  subject: 'Invoice attached',
  markdown: '# Invoice\n\nPlease find attached.',
  attachments: ['./invoice.pdf'],
});
```

--------------------------------

### List Files

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/drive.md

Commands for listing files in a folder or filtering by metadata query.

```bash
# List root folder (most recently modified first)
npx go-drive <account> ls

# List specific folder
npx go-drive <account> ls <folderId>

# With metadata query
npx go-drive <account> ls --query="name contains 'report'"

# Combine folder + query + pagination
npx go-drive <account> ls <folderId> --query="mimeType = 'application/pdf'" --max=10
npx go-drive <account> ls --max=50 --page-token=<token>

# Order by name
npx go-drive <account> ls --order="name"
```

--------------------------------

### Get Full Thread

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/gmail.md

Retrieves an entire email conversation thread by its ID. Supports outputting as a default JSON structure or as an mbox file. Mbox files are compatible with standard email clients.

```bash
npx go-gmail <account> thread <threadId>
```

```bash
# Download full thread as mbox file
npx go-gmail <account> thread <threadId> --format=mbox --output=thread.mbox
# → { "ok": true, "format": "mbox", "path": "thread.mbox", "bytes": 12483 }
```

```bash
# Raw mbox bytes to stdout
npx go-gmail <account> thread <threadId> --format=mbox > thread.mbox
```

```bash
# Base64-encoded mbox in JSON (agent-safe)
npx go-gmail <account> thread <threadId> --format=mbox --b64encode
# → { "format": "mbox", "data": "<base64>", "bytes": 12483 }
```

--------------------------------

### Get Thread as Mbox Format

Source: https://github.com/marcfargas/go-easy/blob/main/skills/go-easy/gmail.md

Export an entire email thread as a single mbox file, containing all messages in RFC 2822 format with envelope lines. Requires the sender's email address.

```typescript
import { getThreadMbox } from '@marcfargas/go-easy/gmail';
import * as fs from 'fs';

const mbox: Buffer = await getThreadMbox(auth, 'threadId', 'me@example.com');
fs.writeFileSync('thread.mbox', mbox);
```