Spark CLI on Mac App Store: verifying the helper installation

Spark CLI lets your AI agent read your inbox, calendar, contacts, and meeting notes through Spark Desktop. If you installed Spark from the Mac App Store and Spark CLI can’t be enabled from Spark Settings > AI Agents, you may need to verify the helper installation manually. This article walks you through the steps.

Why verification is needed

Because Mac App Store apps are packaged differently, Spark CLI uses a small helper the first time you set it up. On most Macs, this happens automatically when you click Set Up CLI. On a small number of setups, the helper doesn't initialize on the first try and needs to be verified manually before your AI agent can connect to Spark.

Prerequisites

Before you begin the setup, make sure that:

• You're running Spark 3.29. Spark CLI is not available in Spark Classic.
• You're signed in to at least one email account in Spark.

Step 1. Confirm Spark CLI is enabled in Spark Desktop

1. Launch Spark Desktop on your Mac.
2. Go to Settings > AI Agents.
3. Click Set Up CLI.

If the AI Agents option isn't visible in Settings, see the Known Issues section below before continuing.

Step 2. Verify the helper from Terminal

1. Open the Terminal app on your Mac.
2. Copy this command: spark
3. Paste it into Terminal. 
4. Press return to run it. 

If the helper is set up correctly, you'll see this output:

                    ███████╗██████╗  █████╗ ██████╗ ██╗  ██╗
                    ██╔════╝██╔══██╗██╔══██╗██╔══██╗██║ ██╔╝
                    ███████╗██████╔╝███████║██████╔╝█████╔╝
                    ╚════██║██╔═══╝ ██╔══██║██╔══██╗██╔═██╗
                    ███████║██║     ██║  ██║██║  ██║██║  ██╗
                    ╚══════╝╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝
                          ✦ Live outside the inbox ✦

  Commands:

    accounts         List accounts with calendars, teams, and shared inboxes
    folders          List accounts and folders with message counts
    emails           List emails with optional search filters and pagination
    search           Search emails by topic with keyword and semantic matching
    thread           Print the full thread for a given email message ID
    contacts         Search contacts by name or email
    events           List calendar events for a given time range
    availability     Find mutual free time slots for attendees
    meetings         List meeting transcripts with optional filters and pagination
    meeting          Read a meeting transcript's summary, transcript, and notes
    team             Show detailed information about a team
    draft            Create, edit, or save a draft email (requires triage access)
    comment          Post or edit a team chat comment on a thread (requires triage access)
    action           Perform email actions like archive, pin, snooze, assign (requires triage)
    contact-action   Block, accept, or change category for a contact (requires triage)
    skill            Print or install the AI agent skill for using spark

  Run 'spark <command> --help' for detailed usage.
 

If you see an error message instead, proceed with Step 3.

Step 3. Try these common fixes

Work through these in order, then run the verification command from Step 2 again:

• Quit Spark fully (⌘Q), reopen it, and click Set Up CLI again.
• If you have more than one version of Spark installed on your Mac, keep only one. Extra copies can confuse the helper during setup.
• Open System Settings on your Mac > Privacy & Security > Full Disk Access and make sure Spark is listed and enabled.
• Restart your Mac.

Step 4. Contact us

If the verification step still fails after the fixes above, please contact our support team:

1. Run the verification command from Step 2 again.
2. Email support@sparkmailapp.com with the following details included:  

• The output of the verification command
• Your Spark version (can be checked in Spark Settings > About)
• Your macOS version (can be checked in About This Mac)
• A screenshot of Settings > AI Agents menu

Our support team will confirm what's happening on your Mac and walk you through the next step.

Known Issues

• Set Up CLI button does nothing: make sure Spark is updated to the latest version, then run through Steps 1–3 in this article.
• AI Agents doesn't appear in Settings: most often this means you're using Spark Classic instead of Spark 3, your macOS is below the supported version, or Spark needs a full quit and relaunch after the latest update.

If you’re a Setapp version user, Spark CLI should be installed without the verification step. If it doesn't install, please follow the steps in this article. 

• Read access vs. Triage: Read access allows your AI agent to read your inbox, calendar, contacts, and meeting notes, and works on all plans. Triage access, which allows your AI agent to also move, archive, delete, or reply to emails, requires a Spark Pro plan.

Learn more about Spark CLI and its features in this article. If you need guidance on how to set up Spark CLI with your AI Agents, refer to this guide.