Your automation. The same native engine.

Start with the installed app

The CLI is the executable inside DiskPress.app. There is no separate command-line download. These examples assume the app is installed in Applications. Adjust the path if yours is elsewhere.

"/Applications/DiskPress.app/Contents/MacOS/DiskPress" --help

1. Open DiskPress and go to Settings, then Authorized Paths.
2. Add the specific files or folders the command should be allowed to read and write. For a compressed file, authorize its containing folder.
3. Inspect the selection with scan before choosing optimize.

Commands

Run these after the executable path. Only scan and optimize accept target paths, with a maximum of 500 per request.

paths means permissions. locations means saved optimization targets. They are not interchangeable. Configuration changes and new permission grants remain in the app's Settings.

Options

Useful examples

For convenience in one Terminal session, store the executable path in a variable. This does not install a command or change your shell configuration.

DISKPRESS="/Applications/DiskPress.app/Contents/MacOS/DiskPress"

Inspect your permissions and settings

"$DISKPRESS" paths --json
"$DISKPRESS" settings --json
"$DISKPRESS" locations --json

Scan without optimizing

After authorizing the folder, inspect its eligibility. A scan does not predict the final compression ratio, and some compatibility checks only happen during real optimization.

"$DISKPRESS" scan --json -- "$HOME/Downloads"

Run a one-time optimization

This changes the storage of supported files in the selected folder. Use only a folder you intend to optimize.

"$DISKPRESS" optimize --json --quiet -- "$HOME/Documents"

Show progress when you want it

"$DISKPRESS" optimize --gui -- "$HOME/Documents"

Read the results

"$DISKPRESS" overview --json
"$DISKPRESS" savings --json
"$DISKPRESS" activity --limit 20 --json

To page through Activity, pass the exact returned nextBefore value to --before until hasMore is false. Large records may shorten a page. A cleared or expired cursor returns an error, so restart without --before.

Understand the output

Human-readable progress goes to standard error, with the final summary on standard output. With --json, standard output is a stream of separate JSON objects, one per line. Parse it as NDJSON, not one large JSON document.

• Events include schemaVersion, requestID, sequence, and event. The current schema version is 1.
• Event types are progress, result, and error. Progress is sampled, so sequence numbers can have gaps.
• Use the final event and the process exit code together. A progress message is not proof of completion.
• Results include file counts, compression savings, estimated deduplication savings, and structured reasons for outcomes. Numeric sizes are bytes.

Measurements are not all live scans

locations, savings, and overview read saved measurements. Overview's disk capacity is queried separately at request time. Check measurementAvailable, complete, coverage, and measurement timestamps. Unknown values are null, not zero. Dates are ISO 8601 in UTC.

Current savings cover all saved locations, including disabled ones, with overlapping files counted once. Recent savings describe completed optimization work. Do not add Activity records to current totals or assume every record is a unique file. Catalina cannot measure current deduplication savings.

Use Rescan in the app's Overview for fresh current measurements. A selection scan is not a command to refresh the saved global savings inventory.

Exit codes

Ctrl+C, SIGTERM, or Cancel in the progress window requests a safe stop. Let the process finish. Files already optimized remain optimized.

A sensible AI agent workflow

DiskPress provides the commands. Your agent decides how to invoke them, so give it clear boundaries. A useful starting instruction is below.

Read the help from the executable inside DiskPress.app.
Inspect paths and settings with --json.
Scan only the files or folders I explicitly select.
Explain eligibility and ask before optimizing.
Do not grant permissions or use elevated privileges.
Do not override exclusions unless I explicitly request it.
Use the final JSON event and exit code to report results.

Pass each path as a separate argument after --. Never concatenate an unescaped filename into a shell command. If permission is missing, ask the user to authorize the path in DiskPress instead of retrying in a loop or using sudo.

Read Activity for per-file reasons after warnings or failures. A successful run can save nothing, and a safely skipped file is not necessarily an error. On a recovery error, preserve the files and report the message.

Permissions and safety still apply

All requested targets must be covered by usable saved read/write authorizations before optimization begins. The CLI never opens a permission picker, grants access, or bypasses protected paths. A selected folder can cover descendants, but authorizing one file does not authorize its siblings.

The same compression and deduplication engine, verification, recovery, configured exclusions, and applicable file limits are used by the app and CLI. Apps and executables remain unsupported. An explicit exclusion override never disables safety checks.

Scan and optimization jobs run one at a time in the current macOS login session. Read-only statistics, settings, and Activity commands can run while work is in progress. There is no CLI command to enable a daemon, mutate settings, or undo completed storage changes.

Keep an independent backup. See the FAQ on verification and recovery before automating important data.