macOS Contacts CLI 是一款专为 macOS 设计的命令行工具，通过系统原生框架 `CNContactStore` 实现对通讯录的读写操作。该工具统一整合了 iCloud、本地以及 Exchange 等多种来源的联系人群组，确保用户能够在一个界面中管理所有联系人数据。其核心优势在于支持原子化写入操作，避免数据不一致问题，同时借助 `osascript` 脚本绕过 Apple 官方 API 对 iCloud 群组成员管理的限制，从而完整支持联系人分组功能。 该工具由 Python 编写，依赖 pyobjc-framework-Contacts 和 pyyaml 库，首次运行时需在系统设置中为终端授予通讯录访问权限。它提供了一系列子命令，涵盖搜索、展示、创建、更新、删除联系人等常见操作，并支持按姓名、邮箱、电话号码、城市或国家进行精准筛选。输出格式采用 YAML，便于开发者进一步处理或集成到其他自动化流程中。 尽管存在一些已知限制——例如无法通过命令行设置联系人的备注信息（因缺少必要权限），且更新操作仅能追加而非替换电话、邮箱等信息——但整体设计已充分考虑实际使用场景中的兼容性与稳定性。对于需要批量管理联系人或将其嵌入脚本工作流的开发者而言，这是一个高效且可靠的解决方案。
核心功能特点
- 基于 CNContactStore 框架，统一管理 iCloud、本地及 Exchange 联系人
- 支持按姓名、邮箱、电话号码、城市或国家进行多维度搜索
- 提供联系人创建、更新、删除及分组管理功能
- 原子化写入保障数据一致性，避免部分更新导致的数据错误
- YAML 格式输出，便于与其他脚本或工具集成
- 自动处理 iCloud 群组成员变更，绕过官方 API 的限制
适用场景
该工具特别适合需要在自动化脚本中调用通讯录功能的开发者和系统管理员。例如，在部署新设备时快速导入预设联系人；或在企业环境中批量更新员工联系信息，而无需手动打开图形界面逐个操作。由于其支持通过命令行参数精确控制搜索条件，也适用于构建内部管理系统的前端接口，实现“输入关键词→返回联系人列表”的快速检索需求。 对于经常使用终端进行日常工作的技术用户来说，macOS Contacts CLI 可显著提升效率。比如，当忘记某个客户的完整姓名但记得其公司名时，可通过 `search –organization “Acme”` 快速定位；又如，在撰写邮件前，用 `show “Jane Doe”` 查看其所有联系方式，包括社交媒体资料和生日提醒。这些细粒度操作在传统图形界面中往往需要多次点击才能完成。 此外，该工具还适合集成到 CI/CD 流程或远程管理工具中。假设你正在维护一个开源项目，希望自动添加贡献者到项目专属通讯录列表中，只需运行 `add_to_list “Alice” “Contributors”` 即可完成配置，整个过程无需人工干预。这种轻量级、无头（headless）的设计使其成为 DevOps 工作流中不可或缺的一环。