核心用法
zoho CLI 是专为 Zoho Mail 设计的命令行工具，支持邮件读取、搜索、发送、文件夹管理及附件操作。所有命令默认输出结构化 JSON，便于脚本管道处理；也可通过 --md 切换为 Markdown 表格格式。
关键命令速览：
zoho mail list/search/get— 邮件浏览与检索，支持按发件人、主题过滤zoho mail send— 发送邮件，支持 HTML/纯文本、多附件、多收件人zoho mail mark-read/move/spam/delete— 批量邮件状态管理zoho folders list/create/rename/delete— 文件夹操作zoho mail attachments/download-attachment— 附件列表与下载
认证流程： 首次使用需执行 zoho config init 配置 OAuth 客户端凭证，再运行 zoho login 完成浏览器授权。Token 自动存储于系统钥匙串（macOS Keychain/Linux Secret Service/Windows Credential Locker），支持静默刷新，无需手动管理。
显著优点
1. 纯本地工具链：无需第三方代理服务，直接调用 Zoho API，数据不经过中间服务器
2. JSON-first 设计：所有输出结构化，与 jq 等工具无缝集成，适合自动化工作流
3. 跨平台支持：Python 3.11+，支持 macOS/Linux/Windows，提供 brew/uv/pipx 多种安装方式
4. 安全存储：敏感凭据（client_id/secret、access/refresh tokens）默认存入 OS keyring，支持可选的加密文件存储（通过 ZOHO_TOKEN_PASSWORD）
5. 批量操作友好：支持多 Message ID 批量处理，配合 xargs 实现复杂工作流
潜在局限
1. OAuth 配置门槛：需用户自行在 Zoho Developer Console 创建应用并获取 client_id/secret，对非技术用户不够友好
2. Python 依赖：要求 Python 3.11+，老旧系统可能需额外配置
3. 网络直连要求：必须能访问 Zoho API（部分地区可能存在网络稳定性问题）
4. 本地凭据风险：config.json 包含敏感的 OAuth client_secret，需妥善保管文件权限
5. Token 刷新依赖 keyring：headless/CI 环境需额外配置 ZOHO_TOKEN_PASSWORD 环境变量
适合人群
- 需要将 Zoho Mail 集成到自动化脚本的技术用户
- 偏好命令行工作流、追求效率的开发者/运维人员
- 对数据隐私敏感、不愿使用第三方邮件客户端的用户
- 构建邮件处理 Agent 或内部工具的团队
常规风险
| 风险类型 | 说明 | 缓解建议 |
|---------|------|---------|
| 凭据泄露 | config.json 包含 client_secret，误提交至版本控制可能导致账户风险 | 将 config.json 加入 `.gitignore`，设置文件权限 600 |
| 钥匙串访问冲突 | 多用户或 CI 环境下钥匙串访问可能失败 | CI 环境使用 `ZOHO_TOKEN_PASSWORD` 启用加密文件存储 |
| Token 失效 | 长期未使用或 Zoho 安全策略变更可能导致 refresh 失败 | 监控 `token_refresh_failed` 错误，引导用户重新登录 |
| 误操作批量删除 | `delete --permanent` 不可恢复 | 建议先用 `--dry-run` 模式验证（如工具支持）或人工复核 |
| 附件路径遍历 | `download-attachment --out` 参数若处理不当可能覆盖系统文件 | 验证输出路径，避免使用相对路径 `../` 模式 |
技术合规性
- 遵循 OAuth 2.0 标准授权流程
- 支持 Token 自动刷新机制
- 所有网络通信走 HTTPS（依赖 Zoho API）
- 本地存储加密依赖 OS 原生安全设施，符合平台最佳实践