Command line guide

App Trust Preview includes a command line interface for opening analyses in new app windows and exporting reports from automation, shell scripts, security review workflows, and AI agents. It analyzes supported files locally on your Mac.

Start with help

Run the installed app binary directly from Terminal. Quote the path because the app name contains spaces.

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

The help output lists the current options, supported export formats, scan filtering, and test discovery commands.

Open an analysis window

Use --open when you want App Trust Preview to analyze a target and show the report in the app.

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

The command opens the analysis in a new window, including when the main app is already running. This makes it suitable for automation such as showing an analysis whenever a new app is added to a watched folder.

Do not use either of these Launch Services forms.

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

Passing the target directly to open -b is blocked by a macOS privacy dialog.

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

Using --args only passes the target when the main app is not already running. Use the App Trust Preview binary with --open to avoid both problems.

If the Mac App Store build cannot hand off the target, install or update the optional inspection script from the main app and try again.

Start with report details expanded

Launch the app with --expand-details to open report views with detail sections expanded. Use this as a separate launch command. --open accepts only its target path.

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

Supported targets

The CLI accepts the same practical file types as the app.

  • .app bundles
  • .pkg installer packages
  • .dmg disk images
  • Binary executables
  • Executable scripts

Export reports

Use --export json when another tool or AI agent will parse the report. Use --export txt when a person will read it.

'/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"

Omit --output to write JSON or text to standard output. These reports include security findings, update delivery checks, compatibility details, download history, and file metadata. The app interface can also export PDF and PNG image reports for records and support notes.

Choose JSON evidence detail

JSON exports use --evidence summary by default. Add --evidence full to include raw command output in the JSON report.

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

Review reports before sharing them. Network URLs are exported unchanged and may contain private query values or fragments.

Validate a saved JSON report

Use --validate-report to check a saved JSON report's structure and internal consistency without rescanning the target. A valid report does not prove that the inspected software is safe.

'/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

Add --json to return valid, issueCount, and issues as JSON. This flag is supported for report validation and test discovery. For report export, use --export json instead.

Save an app as APP, ZIP, or DMG

Use --save-app to save the app bundle itself. Choose app, zip, or dmg and supply --target and --output.

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

The source must be an .app bundle. Use a new destination with the matching .app, .zip, or .dmg extension in an existing writable folder. The destination cannot be inside the source app or the running App Trust Preview bundle.

In the Mac App Store build, install or update the optional AppTrustPreviewInspect helper from the main app before saving apps. The Setapp build uses its bundled helper.

Scan filtering

By default the CLI runs every available scan. You can discover test keys and ask for a smaller set when you need faster automation.

'/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

The special value all requests every scan. Identity is always included, and App Trust Preview adds required dependency scans automatically.

Allowed paths

Open App Trust Preview Settings and choose Allowed Paths before using automation outside the default app folders. Add folders where targets may live with read access. /Applications already has read-only access.

  • Add ~/Downloads if downloaded apps, installers, disk images, binaries, or scripts are stored there.
  • Add ~/Applications if you keep per-user apps there.
  • Add a report output folder with read and write access if automation should save files there.

If a target or output path cannot be reached, the CLI prints guidance that points back to the same Settings pane.

Handle output and exit codes

Read reports and validation results from stdout, and error messages from stderr. For export, validation, app saving, and opening a target, exit code 0 means the command succeeded, 1 means an operation failed or validation found issues, and 2 means invalid arguments or an unreadable or malformed report. Successful export does not mean the software is safe.

Use with AI agents

App Trust Preview can give an AI agent local evidence without uploading inspected software to a third party. The most reliable workflow is to make the agent learn the current CLI from --help, then read report output from standard output instead of guessing export flags.

  1. Open Settings in App Trust Preview and choose Allowed Paths.
  2. Keep /Applications for installed apps. It is already available as read only.
  3. Add ~/Downloads or ~/Applications with read access when those folders contain targets.
  4. Add a report folder with read and write access only when the agent should save files there.
  5. Tell the agent to run '/Applications/App Trust Preview.app/Contents/MacOS/App Trust Preview' --help and read the help text from stdout before choosing options.
  6. Ask the agent to inspect specific targets with --export json --target <path> and read the report from stdout. Omit --output unless a saved file is needed.
  7. If you do want saved JSON or text files, give the agent an explicit writable output folder and tell it to use the documented export option from --help.
Run '/Applications/App Trust Preview.app/Contents/MacOS/App Trust Preview' --help first and read stdout.
Use only the options documented there.
Prefer report output on stdout.
Do not use --json for report export.
Do not write report files unless I provide an output folder with write access.

A useful AI prompt is to ask for identity, signing and timestamp validity, notarization, update delivery safety, sandboxing, privacy requests, saved permission decisions, app and component compatibility, logical and on-disk size, download provenance, package contents, helper safety, network access, executable hashes, VirusTotal report links, and unusual technical indicators for every target in a folder.