feat(gmail): add label CRUD and apply/remove commands

plosson · claude · plosson · commit e381ba4acfb5 · 2026-04-28T11:57:54.000+02:00
Adds `gmail labels {list,create,delete,rename}` for managing labels
and `gmail label &lt;id...&gt;` with repeatable --apply/--remove and a
--thread switch for operating on messages or threads. System labels
are blocked from delete/rename but can be applied/removed (so
--remove INBOX archives, --apply STARRED stars).

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -137,6 +137,11 @@ agentio gmail send --to <email> --subject <subject> [--body <body>] [--attachmen
 agentio gmail draft --to <email> --subject <subject> [--body <body>] [--attachment <path>] [--reply-to <thread-id>]
 agentio gmail archive <message-id...>
 agentio gmail mark <message-id...> --read|--unread
+agentio gmail labels list
+agentio gmail labels create <name>            # "/" nests in the Gmail UI
+agentio gmail labels delete <name-or-id>      # user labels only
+agentio gmail labels rename <old> <new>
+agentio gmail label <id...> [--apply <name>]... [--remove <name>]... [--thread]
 agentio gmail attachment <message-id> [--output <dir>]
 agentio gmail export <message-id> [--output <path>]  # Export as PDF
 agentio gmail profile add|list|remove
diff --git a/claude/skills/agentio-gmail/SKILL.md b/claude/skills/agentio-gmail/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: agentio-gmail
-description: Use when interacting with Gmail - list, read, search, send (with attachments/inline images), draft, reply (via --reply-to), archive, mark, download attachments, or export to PDF. Requires agentio CLI with a configured Gmail profile.
+description: Use when interacting with Gmail - list, read, search, send (with attachments/inline images), draft, reply (via --reply-to), archive, mark, manage labels (list/create/delete/rename, apply/remove on messages or threads), download attachments, or export to PDF. Requires agentio CLI with a configured Gmail profile.
 ---
 
 # Gmail Operations with agentio
@@ -111,6 +111,26 @@ agentio gmail mark <message-id> --read
 agentio gmail mark <message-id> --unread
 ```
 
+## Manage Labels
+
+```bash
+agentio gmail labels list
+agentio gmail labels create <name>            # Use "/" for nesting, e.g. "auto/receipts"
+agentio gmail labels delete <name-or-id>      # User labels only (system labels refused)
+agentio gmail labels rename <old> <new>
+```
+
+## Apply / Remove Labels
+
+```bash
+agentio gmail label <id...> [--apply <name>]... [--remove <name>]... [--thread]
+```
+
+- `--apply` and `--remove` are repeatable and can be combined in one call.
+- IDs are message IDs by default; pass `--thread` to operate on threads instead.
+- Labels can be referenced by name or ID. System labels (`INBOX`, `STARRED`, `UNREAD`, `IMPORTANT`, ...) work too — e.g. `--remove INBOX` archives, `--apply STARRED` stars.
+- Idempotent: applying a label that's already present (or removing one that isn't) is a successful no-op.
+
 ## Download Attachments
 
 ```bash
diff --git a/src/commands/gmail.ts b/src/commands/gmail.ts
@@ -7,7 +7,7 @@ import { setProfile, getProfile } from '../config/config-manager';
 import { createProfileCommands } from '../utils/profile-commands';
 import { performOAuthFlow } from '../auth/oauth';
 import { GmailClient } from '../services/gmail/client';
-import { printMessageList, printMessage, printSendResult, printDraftResult, printArchived, printMarked, printAttachmentList, printAttachmentDownloaded, raw } from '../utils/output';
+import { printMessageList, printMessage, printSendResult, printDraftResult, printArchived, printMarked, printAttachmentList, printAttachmentDownloaded, printLabelList, printLabelCreated, printLabelDeleted, printLabelRenamed, printLabelModified, raw } from '../utils/output';
 import { CliError, handleError } from '../utils/errors';
 import { readStdin } from '../utils/stdin';
 import { enforceWriteAccess } from '../utils/read-only';
@@ -330,6 +330,107 @@ Query Syntax Examples:
       }
     });
 
+  const labels = gmail
+    .command('labels')
+    .description('Manage Gmail labels');
+
+  labels
+    .command('list')
+    .description('List all labels')
+    .option('--profile <name>', 'Profile name (optional if only one profile exists)')
+    .action(async (options) => {
+      try {
+        const { client } = await getGmailClient(options.profile);
+        const result = await client.listLabels();
+        printLabelList(result);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  labels
+    .command('create')
+    .argument('<name>', 'Label name (use "/" for nesting, e.g. "auto/receipts")')
+    .description('Create a new label')
+    .option('--profile <name>', 'Profile name (optional if only one profile exists)')
+    .action(async (name: string, options) => {
+      try {
+        const { client, profile } = await getGmailClient(options.profile);
+        await enforceWriteAccess('gmail', profile, 'create label');
+        const result = await client.createLabel(name);
+        printLabelCreated(result);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  labels
+    .command('delete')
+    .argument('<name-or-id>', 'Label name or ID')
+    .description('Delete a user label')
+    .option('--profile <name>', 'Profile name (optional if only one profile exists)')
+    .action(async (nameOrId: string, options) => {
+      try {
+        const { client, profile } = await getGmailClient(options.profile);
+        await enforceWriteAccess('gmail', profile, 'delete label');
+        const result = await client.deleteLabel(nameOrId);
+        printLabelDeleted(result.name, result.id);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  labels
+    .command('rename')
+    .argument('<old>', 'Existing label name or ID')
+    .argument('<new>', 'New label name')
+    .description('Rename a user label')
+    .option('--profile <name>', 'Profile name (optional if only one profile exists)')
+    .action(async (oldName: string, newName: string, options) => {
+      try {
+        const { client, profile } = await getGmailClient(options.profile);
+        await enforceWriteAccess('gmail', profile, 'rename label');
+        const result = await client.renameLabel(oldName, newName);
+        printLabelRenamed(oldName, result);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  gmail
+    .command('label')
+    .argument('<id...>', 'Message ID(s) (or thread ID(s) with --thread)')
+    .description('Apply and/or remove labels on messages or threads')
+    .option('--profile <name>', 'Profile name (optional if only one profile exists)')
+    .option('--apply <name>', 'Label to apply (name or ID, repeatable)', (val: string, acc: string[]) => [...acc, val], [])
+    .option('--remove <name>', 'Label to remove (name or ID, repeatable)', (val: string, acc: string[]) => [...acc, val], [])
+    .option('--thread', 'Treat IDs as thread IDs')
+    .action(async (ids: string[], options) => {
+      try {
+        const apply = options.apply as string[];
+        const remove = options.remove as string[];
+        if (!apply.length && !remove.length) {
+          throw new CliError('INVALID_PARAMS', 'Specify at least one --apply or --remove');
+        }
+
+        const { client, profile } = await getGmailClient(options.profile);
+        await enforceWriteAccess('gmail', profile, 'modify labels');
+
+        const [addLabelIds, removeLabelIds] = await Promise.all([
+          client.resolveLabelIds(apply),
+          client.resolveLabelIds(remove),
+        ]);
+
+        const isThread = options.thread === true;
+        for (const id of ids) {
+          await client.modifyLabels(id, addLabelIds, removeLabelIds, isThread);
+          printLabelModified(id, isThread, apply, remove);
+        }
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
   gmail
     .command('attachment')
     .argument('<message-id>', 'Message ID')
diff --git a/src/services/gmail/client.ts b/src/services/gmail/client.ts
@@ -1,7 +1,7 @@
 import { gmail, type gmail_v1 } from '@googleapis/gmail';
 import type { OAuth2Client } from 'google-auth-library';
 import { basename } from 'path';
-import type { GmailMessage, GmailListOptions, GmailSendOptions, GmailAttachment, GmailAttachmentInfo } from '../../types/gmail';
+import type { GmailMessage, GmailListOptions, GmailSendOptions, GmailAttachment, GmailAttachmentInfo, GmailLabel } from '../../types/gmail';
 import type { ServiceClient, ValidationResult } from '../../types/service';
 import { CliError } from '../../utils/errors';
 
@@ -588,6 +588,128 @@ export class GmailClient implements ServiceClient {
     }
   }
 
+  private mapLabel(label: gmail_v1.Schema$Label): GmailLabel {
+    return {
+      id: label.id!,
+      name: label.name!,
+      type: label.type === 'system' ? 'system' : 'user',
+      ...(label.messageListVisibility ? { messageListVisibility: label.messageListVisibility } : {}),
+      ...(label.labelListVisibility ? { labelListVisibility: label.labelListVisibility } : {}),
+    };
+  }
+
+  async listLabels(): Promise<GmailLabel[]> {
+    try {
+      const response = await this.gmail.users.labels.list({ userId: 'me' });
+      const labels = (response.data.labels || []).map((l) => this.mapLabel(l));
+      labels.sort((a, b) => {
+        if (a.type !== b.type) return a.type === 'system' ? -1 : 1;
+        return a.name.localeCompare(b.name);
+      });
+      return labels;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new CliError('API_ERROR', `Gmail API error: ${message}`);
+    }
+  }
+
+  async createLabel(name: string): Promise<GmailLabel> {
+    try {
+      const response = await this.gmail.users.labels.create({
+        userId: 'me',
+        requestBody: {
+          name,
+          messageListVisibility: 'show',
+          labelListVisibility: 'labelShow',
+        },
+      });
+      return this.mapLabel(response.data);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new CliError('API_ERROR', `Failed to create label: ${message}`);
+    }
+  }
+
+  async deleteLabel(nameOrId: string): Promise<{ id: string; name: string }> {
+    const label = await this.resolveLabel(nameOrId);
+    if (label.type === 'system') {
+      throw new CliError('INVALID_PARAMS', `Cannot delete system label: ${label.name}`);
+    }
+    try {
+      await this.gmail.users.labels.delete({ userId: 'me', id: label.id });
+      return { id: label.id, name: label.name };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new CliError('API_ERROR', `Failed to delete label: ${message}`);
+    }
+  }
+
+  async renameLabel(oldNameOrId: string, newName: string): Promise<GmailLabel> {
+    const label = await this.resolveLabel(oldNameOrId);
+    if (label.type === 'system') {
+      throw new CliError('INVALID_PARAMS', `Cannot rename system label: ${label.name}`);
+    }
+    try {
+      const response = await this.gmail.users.labels.patch({
+        userId: 'me',
+        id: label.id,
+        requestBody: { name: newName },
+      });
+      return this.mapLabel(response.data);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new CliError('API_ERROR', `Failed to rename label: ${message}`);
+    }
+  }
+
+  async resolveLabelIds(namesOrIds: string[]): Promise<string[]> {
+    if (namesOrIds.length === 0) return [];
+    const labels = await this.listLabels();
+    const byId = new Map(labels.map((l) => [l.id, l]));
+    const byName = new Map(labels.map((l) => [l.name.toLowerCase(), l]));
+    return namesOrIds.map((input) => {
+      const direct = byId.get(input);
+      if (direct) return direct.id;
+      const named = byName.get(input.toLowerCase());
+      if (named) return named.id;
+      throw new CliError('NOT_FOUND', `Label not found: ${input}`);
+    });
+  }
+
+  private async resolveLabel(nameOrId: string): Promise<GmailLabel> {
+    const labels = await this.listLabels();
+    const direct = labels.find((l) => l.id === nameOrId);
+    if (direct) return direct;
+    const named = labels.find((l) => l.name.toLowerCase() === nameOrId.toLowerCase());
+    if (named) return named;
+    throw new CliError('NOT_FOUND', `Label not found: ${nameOrId}`);
+  }
+
+  async modifyLabels(
+    id: string,
+    addLabelIds: string[],
+    removeLabelIds: string[],
+    isThread: boolean,
+  ): Promise<void> {
+    const requestBody = {
+      ...(addLabelIds.length ? { addLabelIds } : {}),
+      ...(removeLabelIds.length ? { removeLabelIds } : {}),
+    };
+    try {
+      if (isThread) {
+        await this.gmail.users.threads.modify({ userId: 'me', id, requestBody });
+      } else {
+        await this.gmail.users.messages.modify({ userId: 'me', id, requestBody });
+      }
+    } catch (error) {
+      if (this.isNotFoundError(error)) {
+        throw new CliError('NOT_FOUND', `${isThread ? 'Thread' : 'Message'} not found: ${id}`);
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      throw new CliError('API_ERROR', `Failed to modify labels: ${message}`);
+    }
+  }
+
   private isNotFoundError(error: unknown): boolean {
     if (error && typeof error === 'object' && 'code' in error) {
       return (error as { code: unknown }).code === 404;
diff --git a/src/types/gmail.ts b/src/types/gmail.ts
@@ -32,6 +32,14 @@ export interface GmailAttachmentInfo {
   size: number;
 }
 
+export interface GmailLabel {
+  id: string;
+  name: string;
+  type: 'system' | 'user';
+  messageListVisibility?: string;
+  labelListVisibility?: string;
+}
+
 export interface GmailSendOptions {
   to: string[];
   cc?: string[];
diff --git a/src/utils/output.ts b/src/utils/output.ts
@@ -1,5 +1,5 @@
 import { homedir } from 'os';
-import type { GmailMessage, GmailAttachmentInfo } from '../types/gmail';
+import type { GmailMessage, GmailAttachmentInfo, GmailLabel } from '../types/gmail';
 import type { GChatMessage, GChatSpace, GChatMember, GChatUser } from '../types/gchat';
 import type { GDocsDocument, GDocsCreateResult } from '../types/gdocs';
 import type { GDriveFile, GDriveDownloadResult, GDriveUploadResult } from '../types/gdrive';
@@ -116,6 +116,48 @@ export function raw(text: string): void {
   console.log(text);
 }
 
+// Format Gmail label list
+export function printLabelList(labels: GmailLabel[]): void {
+  if (labels.length === 0) {
+    console.log('No labels found');
+    return;
+  }
+  const nameWidth = Math.max(4, ...labels.map((l) => l.name.length));
+  const typeWidth = 6;
+  console.log(`${'NAME'.padEnd(nameWidth)}  ${'TYPE'.padEnd(typeWidth)}  ID`);
+  for (const label of labels) {
+    console.log(`${label.name.padEnd(nameWidth)}  ${label.type.padEnd(typeWidth)}  ${label.id}`);
+  }
+  console.log(`\n${labels.length} label(s)`);
+}
+
+export function printLabelCreated(label: GmailLabel): void {
+  console.log(`Created label: ${label.name}`);
+  console.log(`ID: ${label.id}`);
+}
+
+export function printLabelDeleted(name: string, id: string): void {
+  console.log(`Deleted label: ${name} (${id})`);
+}
+
+export function printLabelRenamed(oldName: string, label: GmailLabel): void {
+  console.log(`Renamed label: ${oldName} -> ${label.name}`);
+  console.log(`ID: ${label.id}`);
+}
+
+export function printLabelModified(
+  id: string,
+  isThread: boolean,
+  applied: string[],
+  removed: string[],
+): void {
+  const target = isThread ? 'thread' : 'message';
+  const parts: string[] = [];
+  if (applied.length) parts.push(`applied [${applied.join(', ')}]`);
+  if (removed.length) parts.push(`removed [${removed.join(', ')}]`);
+  console.log(`${target} ${id}: ${parts.join('; ')}`);
+}
+
 // Google Chat specific formatters
 export function printGChatSendResult(result: { messageId: string; spaceId?: string; isJsonPayload?: boolean }): void {
   console.log('Message sent');
