Back to Details

use-spark

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Using spark

使用spark

spark
is a CLI for the Spark email client. Use it to query the user's mailbox, calendar, contacts, meetings, and team data.
spark
是Spark邮件客户端的一款CLI工具。可用于查询用户的邮箱、日历、联系人、会议及团队数据。

Running spark

运行spark

bash
spark <command> [options]
Environment: 
spark
is a thin client that talks to the user's running Spark macOS Desktop app. 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.
bash
spark <command> [options]
环境说明： 
spark
是一款轻量客户端，需与用户正在运行的Spark macOS桌面应用通信。请勿在沙箱、容器、CI运行器或任何与用户桌面会话隔离的环境中尝试执行它——否则将无法连接。

Commands

命令列表

CommandDescription
accounts
List accounts, calendars, teams, shared inboxes
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
events
List calendar events for a time range
availability
Find free time slots, optionally with attendees
contacts
Search contacts by name or email
team
Show team info, members, shared inboxes, assignments
meetings
List meeting transcripts
meeting
Read a single meeting transcript
命令描述
accounts
列出账户、日历、团队和共享收件箱
folders
列出文件夹/标签及对应邮件数量
emails
通过筛选器和分页功能列出邮件
search
混合关键词+语义搜索，返回完整邮件内容
thread
读取完整对话线程——包含邮件头、正文和附件信息
events
列出指定时间范围内的日历事件
availability
查找空闲时段，可指定参会人员
contacts
通过姓名或邮箱搜索联系人
team
查看团队信息、成员、共享收件箱及任务分配情况
meetings
列出会议纪要
meeting
读取单条会议纪要

accounts

accounts

List all configured accounts with their calendars, teams, and shared inboxes.
bash
spark accounts
Run this first to discover what accounts, calendars, and teams are available.
列出所有已配置的账户及其关联的日历、团队和共享收件箱。
bash
spark accounts
建议先运行此命令，了解可用的账户、日历和团队信息。

folders

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
.
bash
spark folders                        # all accounts
spark folders user@example.com       # single account
列出文件夹及对应邮件数量。输出内容中括号内的是文件夹标识符——可将其作为
emails
和
search
命令的参数。由Google账户支持的邮箱会在邮件账户或共享收件箱标题后显示
(Gmail labels)
。团队名称可作为
emails
命令的有效标识符。
bash
spark folders                        # 所有账户
spark folders user@example.com       # 单个账户

emails

emails

List emails with metadata (ID, From, Date, Subject, Flags). Supports pagination and Gmail-style filters.
bash
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.
Folder identifier formats (run 
folders
to see available ones):
FormatExampleMeaning
Bare name
Inbox
, 
Archive
Unified folder (cross-account)
email
user@example.com
Account inbox shorthand
email:Folder
user@example.com:Archive
Specific account folder
"Team Name"
"My Team"
All shared threads in a team (quote if spaces)
shared@email:Folder
shared@co.com:Inbox
Shared inbox folder
Filter operators (combinable, Gmail-style):
OperatorExample
from:<addr>
from:alice@co.com
to:<addr>
to:bob@co.com
cc:<addr>
cc:team@co.com
subject:<text>
subject:"quarterly report"
before:yyyy/MM/dd
before:2026/03/01
after:yyyy/MM/dd
after:2026/01/01
newer_than:Xd
newer_than:7d
(also 
w
, 
m
, 
y
)
older_than:Xd
older_than:30d
has:attachment
also 
document
, 
spreadsheet
, 
presentation
, 
reminder
is:unread
also 
read
, 
starred
, 
pinned
, 
unreplied
is:shared
emails shared to any team (alias for 
is:shared_email
)
is:shared_inbox_open
open items in shared inbox
is:shared_inbox_done
completed/closed items in shared inbox
category:personal
also 
priority
, 
notification
, 
newsletter
, 
invitation
, 
invitation_response
assigned_to:me
emails assigned to current user
assigned_to:<email>
emails assigned to specific teammate
assigned_to:unassigned
shared inbox items with no assignee
assigned_to:other
emails assigned to someone else (not me)
assigned_by:me
emails delegated by current user
filename:<name>
filename:report.pdf
列出包含元数据（ID、发件人、日期、主题、标记）的邮件。支持分页和Gmail风格的筛选器。
bash
spark emails                                                   # 统一收件箱
spark emails user@example.com:Archive                          # 指定文件夹
spark emails "My Team"                                         # 团队所有共享对话
spark emails --filter "from:alice@co.com is:unread"             # 筛选邮件
spark emails --filter "newer_than:7d has:attachment"            # 近期带附件的邮件
spark emails --page 2 --page-size 20                           # 分页
spark emails --order ascending                                 # 按时间升序（ oldest first）
spark emails --new-senders                                     # 仅显示新发件人的邮件
GateKeeper筛选： 当在显式模式下使用GateKeeper查看收件箱时，新发件人的邮件会被自动过滤，顶部会显示“新发件人”数量。使用
--new-senders
参数可查看这些邮件。
文件夹标识符格式（运行
folders
命令查看可用标识符）：
格式示例含义
纯名称
Inbox
, 
Archive
跨账户统一文件夹
邮箱地址
user@example.com
账户收件箱简写
邮箱地址:文件夹名
user@example.com:Archive
指定账户的文件夹
"团队名称"
"My Team"
团队所有共享对话（名称含空格时需加引号）
共享邮箱:文件夹名
shared@co.com:Inbox
共享收件箱文件夹
筛选运算符（可组合使用，Gmail风格）：
运算符示例
from:<addr>
from:alice@co.com
to:<addr>
to:bob@co.com
cc:<addr>
cc:team@co.com
subject:<text>
subject:"quarterly report"
before:yyyy/MM/dd
before:2026/03/01
after:yyyy/MM/dd
after:2026/01/01
newer_than:Xd
newer_than:7d
（也支持
w
周、
m
月、
y
年）
older_than:Xd
older_than:30d
has:attachment
还支持
document
文档、
spreadsheet
表格、
presentation
演示文稿、
reminder
提醒
is:unread
还支持
read
已读、
starred
星标、
pinned
置顶、
unreplied
未回复
is:shared
共享至任意团队的邮件（
is:shared_email
的别名）
is:shared_inbox_open
共享收件箱中的未处理项
is:shared_inbox_done
共享收件箱中的已完成/已关闭项
category:personal
还支持
priority
优先级、
notification
通知、
newsletter
通讯、
invitation
邀请、
invitation_response
邀请回复
assigned_to:me
分配给当前用户的邮件
assigned_to:<email>
分配给特定团队成员的邮件
assigned_to:unassigned
共享收件箱中未分配的项
assigned_to:other
分配给其他用户（非当前用户）的邮件
assigned_by:me
当前用户委派的邮件
filename:<name>
filename:report.pdf

search

search

Hybrid keyword + semantic search returning up to 20 emails with full bodies, sorted by relevance.
bash
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
ParameterRequiredDescription
<about>
YesSearch topic (positional)
--filter
NoGmail-style filter (same operators as 
emails
)
--in
NoScope: account, team, folder, or shared inbox. All folders if omitted.
Use 
search
when the user asks about a topic. It returns email bodies so you can answer questions about content. Use 
emails
when listing/browsing by folder or filters without needing bodies.
混合关键词+语义搜索，最多返回20封按相关性排序的完整邮件。
bash
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              # 账户下所有文件夹
参数是否必填描述
<about>
是搜索主题（位置参数）
--filter
否Gmail风格筛选器（与
emails
命令的运算符相同）
--in
否搜索范围：账户、团队、文件夹或共享收件箱。省略则搜索所有文件夹。
当用户询问特定主题时使用
search
命令，它会返回邮件正文，便于你回答内容相关问题。当仅需按文件夹或筛选器列出/浏览邮件而不需要正文时，使用
emails
命令。

thread

thread

Print every message in a thread - headers, full plain-text bodies, and attachment info. After the thread summary line, lists custom (non-system) folder labels once for the whole thread, using qualified names like 
account@domain.com:MyLabel
(same style as 
folders
).
bash
spark thread 1114                          # by message ID from emails/search output
spark thread --download-attachments 1114   # also fetch attachments via IMAP
Use 
emails
or 
search
to find message IDs (the ID column), then 
thread
to read the full conversation.
打印对话线程中的每一条消息——包含邮件头、完整纯文本正文和附件信息。在对话摘要行之后，会列出整个线程的自定义（非系统）文件夹标签，格式为
account@domain.com:MyLabel
（与
folders
命令的格式一致）。
bash
spark thread 1114                          # 通过emails/search输出中的消息ID查询
spark thread --download-attachments 1114   # 同时通过IMAP获取附件
先使用
emails
或
search
命令查找消息ID（ID列），再使用
thread
命令读取完整对话。

events

events

List calendar events for a time range.
bash
spark events                                          # today's remaining events
spark events --tomorrow
spark events --week
spark events --week --in user@example.com             # specific account
spark events --week --in user@example.com:Work        # specific calendar
spark events --start 2026-03-16 --end 2026-03-20      # custom range
Date formats: 
yyyy-MM-dd
, 
dd/MM/yyyy
, or 
yyyy-MM-ddTHH:mm
.
Run 
accounts
to see available calendar accounts and calendar names.
列出指定时间范围内的日历事件。
bash
spark events                                          # 今日剩余事件
spark events --tomorrow
spark events --week
spark events --week --in user@example.com             # 指定账户
spark events --week --in user@example.com:Work        # 指定日历
spark events --start 2026-03-16 --end 2026-03-20      # 自定义时间范围
日期格式：
yyyy-MM-dd
、
dd/MM/yyyy
或
yyyy-MM-ddTHH:mm
。
运行
accounts
命令查看可用的日历账户和日历名称。

availability

availability

Find free time slots. Without 
--attendees
, shows the user's own availability. With 
--attendees
, computes mutual free windows.
bash
spark availability                                                        # today
spark availability --tomorrow
spark availability --week --attendees alice@co.com
spark availability --start 2026-03-16 --end 2026-03-20 --attendees a@co.com,b@co.com
Free slots are within working hours (08:00-20:00), skip weekends, and ignore events marked "free".
查找空闲时段。不带
--attendees
参数时，显示当前用户的空闲时间；带
--attendees
参数时，计算所有参会人员的共同空闲窗口。
bash
spark availability                                                        # 今日
spark availability --tomorrow
spark availability --week --attendees alice@co.com
spark availability --start 2026-03-16 --end 2026-03-20 --attendees a@co.com,b@co.com
空闲时段限定在工作时间（08:00-20:00），跳过周末，且忽略标记为“空闲”的事件。

contacts

contacts

Search contacts by name or email. Strict match first, then fuzzy fallback.
bash
spark contacts "john"
spark contacts "example.com"
通过姓名或邮箱搜索联系人。优先精确匹配，再进行模糊匹配。
bash
spark contacts "john"
spark contacts "example.com"

team

team

Show team info - metadata, shared inboxes with members, full member list, assigned emails, assignment summary.
bash
spark team                     # list available teams
spark team "Readdle"           # specific team
查看团队信息——元数据、含成员的共享收件箱、完整成员列表、已分配邮件及任务分配摘要。
bash
spark team                     # 列出可用团队
spark team "Readdle"           # 指定团队

meetings

meetings

List meeting transcripts with optional filters and pagination.
bash
spark meetings
spark meetings --filter "newer_than:30d"
spark meetings --filter "subject:standup" --page-size 10
Filter operators: 
subject:<text>
, 
before:yyyy/MM/dd
, 
after:yyyy/MM/dd
, 
newer_than:Xd
, 
older_than:Xd
.
列出会议纪要，支持筛选器和分页。
bash
spark meetings
spark meetings --filter "newer_than:30d"
spark meetings --filter "subject:standup" --page-size 10
筛选运算符：
subject:<text>
、
before:yyyy/MM/dd
、
after:yyyy/MM/dd
、
newer_than:Xd
、
older_than:Xd
。

meeting

meeting

Read a single meeting transcript's summary. Optionally include the full transcript and/or notes.
bash
spark meeting 42                            # summary only
spark meeting --transcript 42               # include transcript
spark meeting --notes 42                    # include notes
spark meeting --transcript --notes 42       # everything
Use 
meetings
to find meeting IDs.
读取单条会议纪要的摘要。可选择包含完整纪要和/或会议笔记。
bash
spark meeting 42                            # 仅摘要
spark meeting --transcript 42               # 包含会议纪要
spark meeting --notes 42                    # 包含会议笔记
spark meeting --transcript --notes 42       # 全部内容
使用
meetings
命令查找会议ID。

Smart Categories

智能分类

Spark automatically classifies incoming email into six categories. Use the 
category:
filter operator with 
emails
and 
search
to view mail by category.
CategoryFilterTypical Content
Priority
category:priority
Auto-prioritized or manually marked as priority
People
category:personal
Direct person-to-person email
Notifications
category:notification
Service notifications, alerts, receipts
Newsletters
category:newsletter
Subscriptions, digests, marketing
Invites
category:invitation
Calendar invitations
Invite Responses
category:invitation_response
RSVPs, accepts, declines
Browse by category:
bash
spark emails Inbox --filter "category:priority is:unread"       # unread priority mail
spark emails Inbox --filter "category:personal is:unread"       # unread people mail
spark emails Inbox --filter "category:invitation"               # pending invites
spark emails Inbox --filter "category:notification is:unread"   # unread notifications
spark emails Inbox --filter "category:newsletter newer_than:7d" # recent newsletters
Category-first review pattern: Process inbox in priority order - priority first, then people, then invites, then notifications, then newsletters. This ensures the most important messages get attention first.
Spark会自动将收到的邮件分为6个类别。在
emails
和
search
命令中使用
category:
筛选运算符，可按类别查看邮件。
类别筛选器典型内容
优先级
category:priority
自动标记或手动设置为优先级的邮件
个人邮件
category:personal
直接的个人往来邮件
通知邮件
category:notification
服务通知、提醒、收据
通讯邮件
category:newsletter
订阅内容、合集、营销邮件
邀请邮件
category:invitation
日历邀请
邀请回复
category:invitation_response
回复邀请、接受/拒绝通知
按类别浏览：
bash
spark emails Inbox --filter "category:priority is:unread"       # 未读优先级邮件
spark emails Inbox --filter "category:personal is:unread"       # 未读个人邮件
spark emails Inbox --filter "category:invitation"               # 待处理邀请
spark emails Inbox --filter "category:notification is:unread"   # 未读通知邮件
spark emails Inbox --filter "category:newsletter newer_than:7d" # 近期通讯邮件
优先按类别处理模式： 按优先级顺序处理收件箱——先处理优先级邮件，再处理个人邮件，接着是邀请邮件、通知邮件，最后是通讯邮件。这样能确保最重要的消息优先得到关注。

Typical Workflows

典型工作流

Answer a question about emails:
  1. spark search "topic"
    - find relevant emails with bodies
  2. Read the output and answer the user's question
Find and read a specific email:
  1. spark emails --filter "from:sender subject:keyword"
    - locate the email
  2. spark thread <ID>
    - read the full conversation
Check someone's schedule for a meeting:
  1. spark availability --tomorrow --attendees alice@co.com,bob@co.com
  2. Suggest a time from the free slots
Get team workload overview:
  1. spark team "Team Name"
    - see members and assigned emails
Look up a contact:
  1. spark contacts "name or domain"
    - find their email address
Review assigned shared inbox items:
  1. spark emails shared@co.com:Inbox --filter "assigned_to:unassigned"
    - unassigned items
  2. spark emails --filter "assigned_to:bob@co.com"
    - items assigned to a teammate
  3. spark emails --filter "is:shared_inbox_open"
    - all open shared inbox items
  4. spark emails --filter "is:shared_inbox_done"
    - completed items
Read meeting notes:
  1. spark meetings --filter "newer_than:30d"
    - find recent meetings
  2. spark meeting <ID> --transcript --notes
    - read summary, transcript, and notes
回答邮件相关问题：
  1. spark search "topic"
    - 查找包含正文的相关邮件
  2. 读取输出内容并回答用户的问题
查找并读取特定邮件：
  1. spark emails --filter "from:sender subject:keyword"
    - 定位目标邮件
  2. spark thread <ID>
    - 读取完整对话
查看参会人员的会议日程：
  1. spark availability --tomorrow --attendees alice@co.com,bob@co.com
  2. 从空闲时段中建议合适的会议时间
获取团队工作量概览：
  1. spark team "Team Name"
    - 查看成员及已分配邮件情况
查询联系人：
  1. spark contacts "name or domain"
    - 查找联系人邮箱地址
查看共享收件箱的任务分配：
  1. spark emails shared@co.com:Inbox --filter "assigned_to:unassigned"
    - 未分配的项
  2. spark emails --filter "assigned_to:bob@co.com"
    - 分配给指定团队成员的项
  3. spark emails --filter "is:shared_inbox_open"
    - 共享收件箱中所有未处理项
  4. spark emails --filter "is:shared_inbox_done"
    - 已完成的项
查看会议笔记：
  1. spark meetings --filter "newer_than:30d"
    - 查找近期会议
  2. spark meeting <ID> --transcript --notes
    - 读取摘要、会议纪要和笔记

Keeping this skill up to date

保持技能更新

The CLI and this skill share a single version (
metadata.version
in the front-matter above). New features in newer Spark Desktop releases ship with an updated embedded skill. Backward compatibility is guaranteed within a major version, so the commands and flags documented here keep working - but newly added features won't appear in this file until it is reinstalled.
Check for an update when - and only when - you hit one of these signals:
  • The user asks about a Spark feature, command, or flag that isn't documented here.
  • A 
    spark
    command fails with an "unknown command" or "unknown option" error you didn't expect.
  • The user explicitly says they upgraded Spark or that the skill is out of date.
In those cases:
bash
spark --version
If the printed version is greater than 
metadata.version
above, reinstall and re-read this file before answering:
bash
spark skill --install <parent-of-use-spark>
<parent-of-use-spark>
is the directory containing the 
use-spark/
folder this 
SKILL.md
lives in.
Do not check on every session or before every command - this skill is the source of truth unless one of the signals above tells you otherwise.
CLI工具与本技能共享同一版本（见前文的
metadata.version
）。Spark桌面应用新版本中的新功能会随更新后的内嵌技能一同发布。主版本内保证向后兼容，因此本文档中记录的命令和参数会持续可用——但新增功能需重新安装后才会显示在此文档中。
仅当出现以下情况时，检查是否需要更新：
  • 用户询问的Spark功能、命令或参数未在本文档中记录。
  • spark
    命令执行失败，出现“未知命令”或“未知选项”的意外错误。
  • 用户明确表示已升级Spark或本技能已过时。
出现上述情况时：
bash
spark --version
如果打印的版本高于前文的
metadata.version
，请重新安装并阅读本文档后再回答问题：
bash
spark skill --install <parent-of-use-spark>
<parent-of-use-spark>
是包含本
SKILL.md
所在的
use-spark/
文件夹的上级目录。
请勿在每次会话或每个命令前检查更新——除非出现上述信号，否则本技能即为最新参考。

Tips

提示

  • Always quote multi-word arguments: 
    spark search "project update"
  • Combine filter operators in a single 
    --filter
    string: 
    --filter "from:alice@co.com is:unread newer_than:7d"
  • Use 
    folders
    to discover exact folder identifiers before passing them to 
    emails
    or 
    search --in
  • Use 
    accounts
    to discover calendar names before passing them to 
    events --in
  • The 
    search
    command is best for topic-based queries; 
    emails
    is best for browsing/filtering by metadata
  • thread
    returns the full conversation - use it when you need the complete email text, not just metadata
  • This release is read-only. If the user asks you to send, archive, snooze, assign, or comment - explain that those actions aren't available yet and they'll need to use Spark Desktop directly.
  • 多词参数需加引号：
    spark search "project update"
  • 在单个
    --filter
    字符串中组合多个筛选运算符：
    --filter "from:alice@co.com is:unread newer_than:7d"
  • 在将文件夹标识符传入
    emails
    或
    search --in
    命令前，先使用
    folders
    命令确认准确的标识符
  • 在将日历名称传入
    events --in
    命令前，先使用
    accounts
    命令确认可用的日历名称
  • search
    命令最适合基于主题的查询；
    emails
    命令最适合按元数据浏览/筛选
  • thread
    命令返回完整对话——当你需要完整邮件文本而非仅元数据时使用
  • 当前版本为只读模式。如果用户要求发送、归档、暂缓、分配邮件或添加评论，请说明这些操作目前不可用，需直接使用Spark桌面应用完成。