Spark CLI Skills

---
name: use-spark
description: >-
  Use the spark CLI to access the user's Spark email data - list emails,
  search by topic, read threads, check calendar events, find availability,
  look up contacts, and view team info. Use when the user asks about their
  emails, calendar, contacts, meetings, or scheduling.
metadata:
  version: 1.4.1
  requires:
    bins:
      - spark
---

# Using spark

`spark` is a CLI for the Spark email client. Use it to query the user's mailbox, calendar, contacts, meetings, and team data.

## Running spark

```bash
spark <command> [options]
```

**Environment:** `spark` is a thin client that talks over IPC to the user's running Spark Desktop app - it does not ship its own mailbox, network stack, or credentials. Run it directly on the user's computer against the live Spark Desktop process. Do not try to execute it inside a sandbox, container, CI runner, or any environment isolated from the user's desktop session - it will fail to connect. If Spark Desktop is not running, ask the user to launch it instead of retrying.

**JSON output:** add `--json` to any command to get its result as JSON instead of text - the same data, with full (untruncated) values, snake_case keys, and ISO 8601 dates. A failure prints `{"error": {"message": "…"}}` on stdout and exits non-zero. Prefer the default text when you only need to read the result; use `--json` when you need to process it (e.g. `spark emails --json | jq '.emails[].id'`). Fields are only ever added, never renamed or removed.

## Commands

| Command | Description |
|---------|-------------|
| `accounts` | List accounts, calendars, teams, shared inboxes, and access levels |
| `folders` | List folders/labels with message counts |
| `emails` | List emails with filters and pagination |
| `search` | Hybrid keyword + semantic search with full bodies |
| `thread` | Read full thread - headers, bodies, attachments |
| `attachment` | Read a single email attachment by its ID (auto-downloads) |
| `draft` | Create, edit, or delete an email draft (new, reply, forward, from template), or list account signatures |
| `templates` | List saved message templates (personal and team) |
| `template` | Show a single template by ID or name with its placeholders |
| `comment` | Post a team comment on a thread |
| `events` | List calendar events for a time range |
| `event` | Create, update, delete, or RSVP to a calendar event, including managing attendees / invitations |
| `availability` | Find free time slots, optionally with attendees |