命令行指南

App Trust Preview 包含命令行界面，可在新的应用窗口中打开分析，也可从自动化、Shell 脚本、安全审核工作流和 AI 代理导出报告。它会在你的 Mac 上本地分析支持的文件。

从帮助开始

直接从 Terminal 运行已安装的应用二进制文件。因为应用名称包含空格，所以请给路径加引号。

'/Applications/App Trust Preview.app/Contents/MacOS/App Trust Preview' --help

帮助输出会列出当前选项、支持的导出格式、扫描筛选和测试发现命令。

打开分析窗口

当你希望 App Trust Preview 分析目标并在应用中显示报告时，请使用 --open。

'/Applications/App Trust Preview.app/Contents/MacOS/App Trust Preview' --open "/Volumes/Stats/Stats.app"

此命令会在新窗口中打开分析，即使主应用已经在运行。这适合自动化工作流，例如每当有新应用加入受监视的文件夹时显示分析。

不要使用以下任一种 Launch Services 形式。

open -b com.apptrustpreview.app /Volumes/Stats/Stats.app

直接把目标传给 open -b 会被 macOS 隐私对话框阻止。

open -b com.apptrustpreview.app --args /Volumes/Stats/Stats.app

使用 --args 只会在主应用尚未运行时传递目标。请改用 App Trust Preview 二进制文件和 --open，以避免这两个问题。

如果 Mac App Store 版本无法传递目标，请在主应用中安装或更新可选的检查脚本，然后重试。

启动时展开报告详情

使用 --expand-details 启动应用，让报告视图中的详情部分保持展开。请将它用作单独的启动命令。--open 只接受目标路径。

'/Applications/App Trust Preview.app/Contents/MacOS/App Trust Preview' --expand-details

支持的目标

CLI 接受与应用相同的实用文件类型。

  • .app 应用包
  • .pkg 安装包
  • .dmg 磁盘映像
  • 二进制可执行文件
  • 可执行脚本

导出报告

当另一个工具或 AI 代理要解析报告时，使用 --export json。当报告给人阅读时，使用 --export txt。

'/Applications/App Trust Preview.app/Contents/MacOS/App Trust Preview' --export json --target "/Applications/Example.app" --output "$HOME/Desktop/example-report.json"
'/Applications/App Trust Preview.app/Contents/MacOS/App Trust Preview' --export txt --target "$HOME/Downloads/Example.pkg"

省略 --output 会把 JSON 或文本写到标准输出。这些报告包含安全发现、更新交付检查、兼容性详情、下载历史和文件元数据。应用界面也可以导出 PDF 和 PNG 图片报告，用于记录和支持说明。

选择 JSON 证据详细程度

JSON 导出默认使用 --evidence summary。添加 --evidence full 可在 JSON 报告中包含原始命令输出。

'/Applications/App Trust Preview.app/Contents/MacOS/App Trust Preview' --export json --target "/Applications/Example.app" --evidence full

分享报告前请先检查内容。网络 URL 会原样导出，可能包含私密的查询参数值或片段。

验证已保存的 JSON 报告

使用 --validate-report 检查已保存 JSON 报告的结构和内部一致性，无需重新扫描目标。报告有效并不证明被检查的软件是安全的。

'/Applications/App Trust Preview.app/Contents/MacOS/App Trust Preview' --validate-report "$HOME/Desktop/example-report.json"
'/Applications/App Trust Preview.app/Contents/MacOS/App Trust Preview' --validate-report "$HOME/Desktop/example-report.json" --json

添加 --json 可将 valid、issueCount 和 issues 以 JSON 格式返回。报告验证和测试发现支持此参数。导出报告时请改用 --export json。

将应用保存为 APP、ZIP 或 DMG

使用 --save-app 保存应用包本身。选择 app、zip 或 dmg，并提供 --target 和 --output。

'/Applications/App Trust Preview.app/Contents/MacOS/App Trust Preview' --save-app zip --target "/Applications/Example.app" --output "$HOME/Desktop/Example.zip"

源文件必须是 .app 应用包。在现有的可写文件夹中指定一个尚不存在的目标，并使用对应的 .app、.zip 或 .dmg 扩展名。目标不能位于源应用或正在运行的 App Trust Preview 应用包内部。

使用 Mac App Store 版本时，请先在主应用中安装或更新可选的 AppTrustPreviewInspect 辅助工具，再保存应用。Setapp 版本使用其内置辅助工具。

扫描筛选

默认情况下 CLI 会运行所有可用扫描。需要更快自动化时，你可以发现测试键并请求更小的集合。

'/Applications/App Trust Preview.app/Contents/MacOS/App Trust Preview' --list-tests
'/Applications/App Trust Preview.app/Contents/MacOS/App Trust Preview' --list-tests --json
'/Applications/App Trust Preview.app/Contents/MacOS/App Trust Preview' --export json --target "/Applications/Example.app" --tests signature,notarization,privacyAccesses

特殊值 all 会请求所有扫描。身份信息始终包含，App Trust Preview 会自动加入所需的依赖扫描。

允许路径

在默认应用文件夹之外使用自动化前，打开 App Trust Preview 设置并选择允许路径。添加目标可能所在的文件夹并授予读取访问。/Applications 已经拥有只读访问。

  • 如果下载的应用、安装器、磁盘映像、二进制文件或脚本存放在那里，请添加 ~/Downloads。
  • 如果你把用户级应用放在那里，请添加 ~/Applications。
  • 如果自动化需要保存文件，请添加具有读写访问的报告输出文件夹。

如果无法访问目标或输出路径，CLI 会打印指向同一设置面板的说明。

处理输出和退出码

从 stdout 读取报告和验证结果，从 stderr 读取错误消息。对于导出、验证、保存应用和打开目标，退出码 0 表示命令成功，1 表示操作失败或验证发现问题，2 表示参数无效或报告无法读取、格式错误。导出成功并不表示软件安全。

与 AI 代理一起使用

App Trust Preview 可以在不把被检查软件上传给第三方的情况下，为 AI 代理提供本地证据。最可靠的流程是让代理通过 --help 学习当前 CLI，然后从标准输出读取报告，而不是猜测导出参数。

  1. 打开 App Trust Preview 设置并选择允许路径。
  2. 保留用于已安装应用的 /Applications。它已经以只读方式可用。
  3. 当 ~/Downloads 或 ~/Applications 包含目标时，添加这些文件夹并授予读取访问。
  4. 只有在代理应保存文件时，才添加具有读写访问的报告文件夹。
  5. 让代理运行 '/Applications/App Trust Preview.app/Contents/MacOS/App Trust Preview' --help，并在选择选项前从 stdout 读取帮助文本。
  6. 让代理使用 --export json --target <path> 检查具体目标，并从 stdout 读取报告。除非需要保存文件，否则请省略 --output。
  7. 如果确实想保存 JSON 或文本文件，请给代理一个明确可写的输出文件夹，并让它使用 --help 中记录的导出选项。
先运行 '/Applications/App Trust Preview.app/Contents/MacOS/App Trust Preview' --help 并读取 stdout。
只使用其中记录的选项。
优先从 stdout 获取报告输出。
不要用 --json 导出报告。
除非我提供具有写入权限的输出文件夹，否则不要写入报告文件。

一个有用的 AI 提示是要求它为文件夹中的每个目标检查身份、签名与时间戳有效性、公证、更新交付安全、沙盒、隐私请求、已保存权限决定、应用与组件兼容性、逻辑大小和磁盘占用大小、下载来源、包内容、辅助工具安全性、网络访问、可执行文件哈希、VirusTotal 报告链接和异常技术指标。