Your automation. The same native engine.

Start with the installed app

This guide is for Mac. DiskPress for Files for iPhone and iPad has no CLI or continuous folder monitoring. For iPhone and iPad automation, see Apple Shortcuts workflows and their iOS requirements.

Both the Mac App Store and Setapp versions include the same CLI features. Choose your download. The CLI is the executable inside the app bundle. There is no separate command-line download. These examples use the Mac App Store copy at /Applications/DiskPress.app. Adjust the executable path if your copy is elsewhere.

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

For Setapp, use the executable inside your Setapp installation. Its bundle name and location may differ. The Mac App Store and Setapp editions keep separate settings and saved authorizations, so configure the same edition you invoke. Its built-in --help shows examples using that installation's executable path.

1. Open that copy of 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

--json and --quiet work with all eight commands above. Report commands take no target paths and do not accept --gui or --ignore-exclusions.

What to expect during optimization

The first duplicate check can take longer

When settings and saved-location modes allow both operations, DiskPress combines both techniques in one run. The first duplicate check can take a long time for large folders, including when files are already compressed. Later runs reuse cached fingerprints for unchanged files, even after restarting DiskPress. Matches still undergo content and metadata verification before replacement.

DiskPress also reuses scan results within an optimization and can remember unchanged files that did not benefit from compression. Avoiding another compression attempt does not remove those files from deduplication checks.

Saved-location modes also apply to CLI targets

Choose a location's optimization mode in the app's Locations table. CLI optimization respects that mode, even for files passed individually or with --ignore-exclusions.

• Compress + Deduplicate allows both techniques together.
• Compress Only allows compression but not deduplication.
• Deduplicate Only allows deduplication but not compression.
• Disabled blocks both operations for matching files.

The most specific matching saved location takes precedence. A saved file overrides a containing folder, and a saved child folder overrides its parent, including a disabled parent. A nonrecursive folder rule covers only that folder and its direct children. Files outside saved locations follow the general settings and safety checks.

Deduplication requires both a compatible location mode and the global setting. To disable it globally, turn off "Deduplicate identical files" in Settings. This does not enable compression for Deduplicate Only or Disabled locations. There is no per-command compression-only flag or CLI command to change location modes. CLI runs do not show the first-use deduplication confirmation, including with --gui.

locations --json reports enabled but does not currently include the per-location optimization mode. settings.deduplicationEnabled is the global switch, not a location's mode. Check the Locations table when you need to confirm which operations are allowed.

Recent File Protection does not delay CLI requests

Recent File Protection delays recently changed files during saved-location optimization, including automatic monitoring and Optimize Now. CLI scan and optimize are explicit one-time requests and do not apply this delay, with or without --gui. This is also true when the selected target is a saved location.

The recentFileProtectionSeconds setting reports the saved-location delay, not a CLI waiting period. Schedule commands after the program producing your files has finished writing. Active-writer detection, file-change checks, and verification still apply.

Linked apps still protect their locations

If a saved location has a Linked App, optimization skips its files while that app is running. This also applies to files you name individually through the CLI, and --ignore-exclusions does not bypass it. Quit the linked app before optimizing those files.

locations --json includes linkedApplication with bundleIdentifier, path, and name, or null when none is configured. This describes the saved association, not a live running-app status. A preliminary scan is not a guarantee that a file will pass every check during optimization. See the Linked App FAQ.

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" --version
"$DISKPRESS" paths --json
"$DISKPRESS" settings --json
"$DISKPRESS" locations --json

Scan without optimizing

These examples use a folder of completed data. Replace the path with a specific, mostly stable folder you intend to optimize, and authorize it first. A scan does not predict the final compression ratio, and some compatibility checks only happen during real optimization.

"$DISKPRESS" scan --json -- "$HOME/Documents/Completed Data"

Run a one-time optimization

This changes the storage of supported files in the selected folder and can add disk writes. Avoid repeatedly optimizing locations with frequent new or changing files. See the SSD-write guidance before scheduling commands.

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

Show progress when you want it

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

Read the results

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

The command result describes the finished job. Saved-location totals may still be refreshing. Check savings.refreshing and the measurement dates before treating those totals as updated.

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.
• The final event includes exitCode and message. A result event can describe partial success or cancellation, so check the exit code too.
• CLI labels, help, and generated messages use English. Saved records and shared diagnostics retain their original text. The optional progress window follows the app language.
• Use JSON field names, structured reason codes where provided, and exit codes for automation. Do not match translated or human-readable message text.

Scan and optimization results

scan returns totalFiles, eligibleFiles, potentialDeduplicationFiles, logicalBytes, allocatedBytes, alreadySavedBytes, and the applied minimumFileBytes and maximumFileBytes. Potential deduplication candidates are not confirmed duplicates or a savings prediction.

Scan reasons contain code, count, and message. Reasons can overlap, and an excluded folder counts once because its contents are not enumerated.

optimize returns targets, totalFiles, processedFiles, compressedFiles, deduplicatedFiles, skippedFiles, and failedFiles, plus its initial scan summary and a boolean cancelled. Its top-level reasons are recent human-readable skip or error summaries, not the full per-file history. Read activity for individual outcomes.

Additional outcome counters include alreadyCompressedFiles, insufficientSavingsFiles, and noBenefitFiles. These explain outcomes, not extra files to add to the job total.

Savings appear as compressionSavedBytes, estimatedDeduplicationSavedBytes, and totalEstimatedSavedBytes. Numeric sizes are bytes. Compression and deduplication can affect the same file, so do not add those two file counts to calculate distinct optimized files. Deduplication savings are estimates of shared storage, not a guarantee of an equal increase in free space. Zero savings can be a successful result.

Read progress as snapshots

Each progress event describes the latest state, not an increment to add to the previous event. Use stage counters for a progress bar and job-wide counters for the overall job.

Scroll the table horizontally on smaller screens to read the full reference.

Finding and grouping duplicates can take time without an active filename. Clear old file labels when the new snapshot has no current item. Do not assume a fixed stage order or that a stage reaching its total means the entire command has finished. Only the final event and process exit establish completion.

Measurements are not all live scans

locations, savings, and overview read saved measurements without scanning target files, requesting new permissions, or starting monitoring. They include readAt, dataSource, locationCount, enabledLocationCount, and savings. Dates are ISO 8601 in UTC.

Missing and outdated are different

• measurementAvailable indicates that a location has a saved measurement. Unknown location values are null, not zero.
• measurementStale marks a retained measurement after a failed refresh. DiskPress keeps the last successful values instead of replacing them with zero. Read measurementError and measuredAt for context.
• savings.complete is false if any location is unmeasured or has a stale measurement. unmeasuredLocationCount, staleLocationCount, and oldestMeasurementAt describe coverage and age.
• A saved location's statusSource is last_saved. Its status is not a fresh scan of the target.

Current savings cover measured saved locations, including disabled ones, with overlapping files counted once. A location can have a nonzero size but no credited savings because shared files are already counted elsewhere. Recent savings describe completed optimization work. Do not add Activity records to current totals or assume every record is a unique file.

On Catalina, current deduplication savings cannot be measured. deduplicationMeasurementAvailable is false and those values are null. Deduplication can still run there, and recent savings can include its completed work.

Location availability and authorization

Each entry from locations --json has an availability value of available, unavailable, stale_bookmark, missing, or invalid_authorization. These are saved states, not a fresh permission check. They are separate from the boolean available in paths output.

invalid_authorization means the item at the saved path no longer matches the originally authorized file or folder, for example after restoring a backup. Review the intended target in DiskPress, then remove that saved location and add it again to grant access to the current item. Removing a location does not delete its files. Do not try to bypass the identity check.

The refresh after optimization

After an optimization run, DiskPress refreshes saved-location savings in the background. The CLI can return its final result before this read-only refresh finishes. Reports expose savings.refreshing and savings.refreshError. Use the measurement dates and coverage flags as well, since a finished refresh is not proof that every location was measured successfully.

The host remains open until its commands and the refresh finish, without enabling recurring monitoring. A selection scan or report command alone does not request this refresh. Use Rescan in the app's Overview when you want to refresh saved measurements separately.

Storage and monitoring

savings and overview also include recentSavings for the last 24 hours, 7 days, and 30 days. overview adds storage for the home volume and monitoring. Disk capacity is queried at request time, independently of saved file measurements.

monitoring.enabled is a saved preference. It does not mean the CLI started monitoring. Check monitoring.serviceRunning and monitoring.liveStatusAvailable before displaying live status. When live status is unavailable, live progress fields are null.

Inspect settings and Activity

settings --json returns a settings object with deduplicationEnabled, scanHiddenSystemFiles, recentFileProtectionSeconds, monitoringEnabled, and scanIntervalSeconds. Reading these values does not change them.

Compression thresholds are reported as minimumFileBytes, maximumFileBytes, minimumCompressionSavingsFraction, and minimumCompressionSavingsBytes. These settings describe compression eligibility, not a guarantee that every file will save space.

settings.performance includes level, batteryLevel, separatePowerSettings, and pauseMonitoringOnBattery. Profile values are low_cpu, balanced, fast, or fastest. The current power source and macOS can affect the active performance level.

These profiles also apply to CLI optimization. Fastest scales concurrent work to the Mac's performance-core count, falling back to its physical-core count when needed. Low CPU paces work during large files as well as between files. It is not a fixed CPU percentage limit.

settings.exclusions contains typed rules with id, enabled, type, target, pattern, description, and extensions. Types are file_type, wildcard, regular_expression, and file_group. A rule targets file_name or full_path. File groups include their extensions.

Default exclusions include the databases group. When enabled, it also covers recognized database companion files such as database.sqlite-wal, database.sqlite-shm, and database.sqlite-journal. The reported extensions list contains base database extensions, not every companion filename pattern. Read your configured rules and use scan to inspect exclusion results. Avoid overriding exclusions for active databases.

Page through retained results

activity --json returns activity.records from both GUI and CLI work, newest first. Each record includes id, date, path, name, outcome, originalAllocatedBytes, resultAllocatedBytes, savedBytes, durationSeconds, detail, and locationID. Outcomes are compressed, deduplicated, skipped, failed, or recovered.

To continue, pass the exact returned activity.nextBefore value to --before until activity.hasMore is false. The default page size is 50, and --limit accepts 1 through 500. Large records may shorten a page, so follow the cursor rather than the record count. New records do not shift existing cursors.

A cleared or expired cursor returns an error. Restart without --before. Activity is retained history, not an exhaustive file inventory. Multiple records can refer to one file, and a missing record does not prove that a file was never optimized.

Exit codes and safe cancellation

Ctrl+C, SIGTERM, Cancel, or closing the progress window requests a safe stop. Let the process finish. Files already optimized remain optimized. Losing the terminal client or breaking its output pipe also cancels work.

Removing a saved location involved in an active CLI optimization can also cancel that run from the app. The CLI reports this as cancellation even if you did not press Ctrl+C. Progress can show phase set to cancelling and cancelled set to true. The final cancellation result has exitCode 130 and cancelled set to true. Completed optimizations are kept, and work is not fully stopped until the process exits.

If standard output cannot accept a final result, the process exit code remains authoritative. Do not deliberately cut off a running optimization's output with a command such as head. Use --quiet when you only need the final result.

Accepted requests are not replayed after a host crash. Exit 75 does not prove that no files changed. If the result could not be delivered, review Activity and any recovery message before deciding whether to retry.

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 --version and --help from my installed DiskPress executable.
Use that same edition for permissions, settings, and commands.
Inspect paths, settings, and locations with --json.
Respect saved-location modes. CLI reports do not expose those modes.
Ask me to confirm a mode in Locations if the workflow depends on it.
Scan only the files or folders I explicitly select.
Remember that CLI requests do not apply Recent File Protection.
Explain eligibility and ask before optimizing.
Respect linked apps and wait until files are no longer being written.
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 the job result.
Wait for process exit after cancellation, including app-initiated stops.
Check refreshing, stale flags, and dates before reporting saved totals.
On a missing final result or recovery error, review Activity before retrying.

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. Wait for process exit after requesting cancellation.

Permissions and safety still apply

All requested targets must be covered by usable saved read/write authorizations before optimization begins. If any target lacks access, the command fails before optimizing the other targets. 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.

paths --json returns authorizations with path, directory, access, and available. The access value is readWrite. An unavailable grant may need the volume reconnected or the path authorized again in the same edition of DiskPress.

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. Deduplication groups files only within the same compatible filesystem, never across volumes. An explicit exclusion override never disables safety checks, linked-app protection, or saved-location mode restrictions.

Terminal scan and optimization jobs run one at a time in the current macOS login session and share the app's CPU scheduling, recovery, and accounting. 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.