Use 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

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.

Commands

accounts

List all configured accounts with their aliases, calendars, teams, and shared inboxes. Each account and shared inbox shows its access level in parentheses, which controls what operations Spark can perform.

spark accounts

Run this first to discover what accounts, calendars, and teams are available, and to check their access levels.

Access levels:

Access levels are configured separately for each account and each shared inbox in Spark Desktop under Settings -> AI Agents. Shared inboxes can have a different access level than the parent account - for example, a personal account may have triage access while a shared inbox under the same team is read-only or disabled.

If a command requires a higher access level than the account or shared inbox has, it returns an error with instructions on how to change the level.

folders

List folders with message counts. Output includes folder identifiers in parentheses - use these as arguments to emails and search. Mailboxes backed by a Google account show (Gmail labels) on the Email Account or Shared Inbox header. Teams show the team name as a usable identifier for emails.

spark folders                        # all accounts
spark folders user@example.com       # single account

emails

List emails with metadata (ID, From, Date, Subject, Flags). Supports pagination and Gmail-style filters.

spark emails                                                   # Unified Inbox
spark emails user@example.com:Archive                          # specific folder
spark emails "My Team"                                         # all shared threads in a team
spark emails --filter "from:alice@co.com is:unread"             # filtered
spark emails --filter "newer_than:7d has:attachment"            # recent with attachments
spark emails --page 2 --page-size 20                           # pagination
spark emails --order ascending                                 # oldest first
spark emails --new-senders                                     # show only new sender emails

GateKeeper filtering: When viewing the Inbox with GateKeeper in explicit mode, new sender emails are automatically filtered out and a "New Senders" count is shown at the top. Use --new-senders to view those emails. Use contact-action acceptContact <email> or contact-action blockContact <email> to accept or block a sender.

Folder identifier formats (run folders to see available ones):

Filter operators (combinable, Gmail-style):

search

Two modes:

• With a topic (keyword mode): Hybrid keyword + semantic search returning up to 20 emails with full bodies, sorted by relevance.
• Without a topic (list mode): Paged compact table of every email matching --filter / --in across all folders and all accounts, sorted newest first. Same output as emails, but the default scope is "all folders" instead of the Unified Inbox. Trash, Spam, and Blocked are excluded (matching Spark's search field) unless --in explicitly targets one of those folders.

spark search "quarterly report"
spark search "API integration" --filter "from:alice@co.com"
spark search "budget" --in user@example.com:Archive
spark search "vacation" --in user@example.com              # all folders in account