CozyZip in Terminal
Inspect, create and extract archives with predictable commands and structured results.
The cozyzip executable is included at /Applications/CozyZip.app/Contents/Helpers/cozyzip. The examples below use the optional short command installed through the setup guide. You can substitute the full path instead.
Paths must be absolute. Quote paths containing spaces. Replace the example paths with your own; the commands do not create the example input files.
Inspect or list an archive
cozyzip inspect /absolute/path/example.zip --offset 0 --limit 100
cozyzip list /absolute/path/example.7z
list is an alias of inspect. The result includes archive format, entries, encryption/visibility flags and risk findings. It does not execute archive contents.
Entries and findings are paginated independently. --offset starts at 0; --limit defaults to 200 and must be between 1 and 1000. Follow next_offset and next_findings_offset until each is null. The archive is analysed before its report is paginated.
Reported byte sizes are decimal strings to avoid losing precision in JSON. Unknown uncompressed/entry sizes are null, not zero. A limited-visibility result means CozyZip cannot fully inspect the container; it does not establish that the contents are safe.
Extract to a new folder
Activate your licence in CozyZip Settings before write operations.
cozyzip extract /absolute/path/example.zip --destination /absolute/path/new-output
The destination must be a new directory and its parent must exist. The command refuses an existing destination and does not merge into existing output.
CozyZip checks risk findings before extraction. When a caution or high-risk finding needs your acknowledgement, inspect it first. If you choose to proceed with the reviewed archive:
cozyzip extract /absolute/path/reviewed.zip --destination /absolute/path/new-output --allow-risky
--allow-risky acknowledges review findings, including encrypted or limited-visibility containers. It does not disable path checks or permit unsafe paths/symlinks. Successful extraction can skip unsafe entries: check skipped_count and the reported reasons. Failures can leave partial output at the reported destination; inspect that folder before choosing a different destination for a retry.
Create an archive
cozyzip create /absolute/path/project --destination /absolute/path/project.zip --format zip
cozyzip create /absolute/path/first /absolute/path/second --destination /absolute/path/files.7z --format 7z
cozyzip create /absolute/path/project --destination /absolute/path/project.tar.gz --format tar.gz
Creation supports exactly zip, 7z and tar.gz. Its destination must be a new file with an existing parent directory. It does not replace an existing archive. Source files stay unchanged. Do not place the output archive inside an input folder.
Passwords and encryption
ZIP and 7z support AES-256 encryption. Only 7z can encrypt filenames. TAR.GZ cannot be password protected.
The CLI reads a password from a named environment variable, not a command-line password argument. In an interactive macOS shell:
read -r -s COZYZIP_PASSWORD
export COZYZIP_PASSWORD
cozyzip create /absolute/path/project --destination /absolute/path/private.7z --format 7z --password-env COZYZIP_PASSWORD --encrypt-filenames
unset COZYZIP_PASSWORD
Enter the password when read waits; input is hidden. Use printable ASCII characters, including spaces. For inspection or extraction, pass the same --password-env NAME option. Do not put passwords in scripts, MCP configuration, chat messages or source control. Environment variables are temporary transport, not a password vault; privileged local processes may be able to read them.
Results and exit codes
Success writes one JSON object to stdout:
{"ok":true,"result":{"destination":"/absolute/path/project.7z","format":"7z"}}
Failure writes an error object to stderr:
{"ok":false,"error":{"code":"invalid_arguments","message":"Check the supplied arguments."}}
These are examples of the envelope, not a promise of identical text for every error.
| Exit code | Meaning |
|---|---|
0 |
Success |
1 |
Operation or transport failure |
2 |
Invalid arguments |
--help and --version print plain text. Inspection results include risk_level, findings, entries and pagination cursors. Extraction includes counts for extracted, skipped and renamed entries, plus archive_name_collisions. Check skipped_truncated when the skipped-entry list reaches its limit.
MCP and current limits
cozyzip mcp
This starts a stdio protocol server and waits for an MCP client; it is not an interactive prompt. Read the MCP guide to connect a client.
The current tools inspect, extract and create. They do not edit existing archives, perform integrity-test/checksum commands, or offer search/selective extraction. Those are future priorities, not command flags to invent.
For setup errors, see troubleshooting.