---
layout: layouts/docs.njk
title: "CozyZip in Terminal"
description: "Inspect, create and extract archives with predictable commands and structured results."
permalink: /cozyzip/docs/cli/
markdownURL: /cozyzip/cli.md
---

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](https://cozymacapps.com/cozyzip/docs/). 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

```bash
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.

```bash
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:

```bash
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

```bash
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:

```bash
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:

```json
{"ok":true,"result":{"destination":"/absolute/path/project.7z","format":"7z"}}
```

Failure writes an error object to stderr:

```json
{"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

```bash
cozyzip mcp
```

This starts a stdio protocol server and waits for an MCP client; it is not an interactive prompt. Read the [MCP guide](https://cozymacapps.com/cozyzip/docs/mcp/) 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](https://cozymacapps.com/cozyzip/docs/troubleshooting/).