Use Spark CLI to connect AI agents to your email, calendar, contacts, and meeting notes. Available to all users with Spark Desktop installed.
What is Spark CLI?
Spark CLI is a local command-line interface intended to connect AI agents to your inbox and share emails, calendar, contacts, and meeting notes with them via Spark on your Mac.
Spark CLI is designed to work with agent platforms like Claude Code, Cursor, and OpenClaw. You can also use it with agents powered by local models from Ollama or LM Studio — keeping your email data entirely on your device. It supports all major email providers: Gmail, Outlook, Exchange, iCloud, Yahoo, and more. Connect multiple accounts, and your agent gets unified access across all of them, with no need to configure separate APIs for each provider. You decide which accounts your agent can access, and you can turn access on or off at any time.
Through Spark CLI, your agents can get more than raw email access. Its semantic search is built on Spark's local index, which understands priorities, categories, contact relationships, and conversation context. That means your agent can find relevant information across emails, threads, contacts, calendar events, and meeting notes — with less manual configuration on your end.
Prerequisites
Before setting up Spark CLI, make sure you have:
- Spark Desktop installed and running on your Mac. This is a crucial point for Spark CLI to work.
- At least one email account connected in Spark Desktop (Gmail, Outlook, Exchange, iCloud, Yahoo, or any IMAP/EWS account).
- An AI agent platform you'd like to connect, such as Claude Code, Cursor, or OpenClaw.
What your agent can access
On the free plan, CLI enables read-only access. Your agent can read and search your data but cannot take actions on your behalf. Here's what it can do:
- Read emails, search by keyword or semantic query, and read full threads
- View calendar events and check your availability (or mutual availability with others)
- Access contacts, teams, and meeting notes
- View Spark metadata like priority levels and categories
- Create plain-text drafts via mail-to links
Soon, Spark CLI will enable your agent to act on your inbox per your instructions — creating drafts, organizing messages, and performing bulk operations.
Managing your data
When you use Spark CLI with a local model (Ollama, LM Studio, etc.), no data should leave your device. When you use a cloud-based model, data goes directly to the model provider — Spark does not route your data through its own servers. Semantic indexing always runs locally, regardless of which model you use.
Search options
Spark CLI supports two types of search:
Keyword search works with no additional setup and has no history limitations on any plan.
Semantic search uses Spark's local AI-powered index to find contextually relevant results, not just exact keyword matches. Because the index already understands priorities, categories, and conversation context, your agent can surface the right information without needing detailed filters. To enable it, go to Spark Settings > Spark + AI > AI Assistant and turn it on. This is a one-time step and does not consume any AI tokens. The index runs entirely on your device.
Semantic search history depends on your plan:
- Free: 1 month of search history
- Premium / Plus: 1 year of search history
- Pro: unlimited search history
How to set up Spark CLI
Here are the steps needed for the installation and proper setup of Spark CLI:
- Launch Spark Desktop on your Mac.
- Go to Settings > AI Agents.
- Under Connect AI Agents, click Setup CLI.
- In a pop-up that appears, click Continue to set up agent access.
- Choose what agents can access for each account. You can also set the access level for meeting notes.
- Select your preferred agent.
- Follow the onscreen instructions for your specific agent.
- Once you’re ready, click Finish setup.
How to use Spark CLI
Spark CLI lets your AI agent read and understand your inbox so it can help you act on what's there. A few ways to put it to work:
- Pull together emails, calendar events, and meeting notes related to a specific person or topic.
- Get a snapshot of what's ahead: upcoming meetings, unread messages that need attention, approaching deadlines, and outstanding to-dos.
- Summarize your day or week: meetings attended, decisions made, emails sent, and anything you still owe someone.
- Surface messages still waiting for a response so nothing important slips through.
- Before a call, pull up the latest emails, meeting notes, and context for the attendees or topic so you walk in prepared.
- Combine Spark CLI with other tools your agent can access — like Notion or a task manager — to kick off workflows automatically. For example, when an email is pinned, your agent could create a task or draft a follow-up.
- Scan recent threads for commitments: anything you've promised to do, or anything others owe you. Useful before a check-in or at the end of a busy week.
- Instead of scrolling through a long thread, ask your agent for the key points: who said what, what was decided, and what's still open.
- Before emailing someone you haven't spoken to in a while, pull up your recent history — past conversations, meetings, and shared notes — so you can pick up where you left off.
Spark CLI comes with some pre-built skills. To browse the full list, visit Spark CLI’s repo on GitHub.