---
layout: layouts/docs.njk
title: "Troubleshoot CLI and MCP setup"
description: "Check installation paths, client configuration, licences and archive-operation errors."
permalink: /cozyzip/docs/troubleshooting/
markdownURL: /cozyzip/troubleshooting.md
---

## The command cannot be found

Try the bundled executable directly:

```bash
/Applications/CozyZip.app/Contents/Helpers/cozyzip --version
```

If this works, the short command's link or PATH is missing. Follow the [Terminal setup](https://cozymacapps.com/cozyzip/docs/) rather than downloading a separate CLI package. Check whether the app was moved or renamed; a link to a removed app will stop working. If another `cozyzip` command already exists, identify it before changing anything. The bundled installer refuses to replace it.

## macOS will not open the app or executable

Check that you have an Apple Silicon Mac with macOS 26 or later and a current release from the [official download page](https://cozymacapps.com/cozyzip/download/). Open the installed app normally first. Do not disable Gatekeeper, strip quarantine, re-sign the app or edit its bundle to bypass a warning. Contact support if a verified official download cannot be opened.

## Creating or extracting needs a licence

Open **CozyZip → Settings → Licence** and activate your key. Do not put the licence key in an MCP config or give it to an assistant. Personal and commercial usage terms still apply to automation; there is no separate MCP API key to request. If activation is refused, follow the app's message or contact support instead of changing local licence files.

## The MCP client shows no tools

- Confirm the full executable's `--version` and `--help` work.
- Use the full executable path, `mcp` as an argument, and stdio transport. Do not configure a localhost URL or HTTP endpoint.
- Validate JSON/TOML syntax and preserve the client's expected top-level object. Check the [client examples](https://cozymacapps.com/cozyzip/docs/mcp/).
- Restart/reload the client and approve the server through its own trust controls.
- Check where the process runs. A Linux/remote environment cannot launch the Mac binary at a path on your laptop.
- Review the client's local server logs, redacting paths and secrets before sharing them.

Running `cozyzip mcp` in Terminal normally waits quietly for protocol messages. That is expected, not a hang. Stop that manual process when finished; your client starts its own server. The server must reserve stdout for protocol messages.

## Only inspection is available

That is the default. If you want creation/extraction tools, deliberately enable `--allow-writes` and restart the server. This changes which tools are available; it does not remove the licence requirement or risk checks.

## Extraction asks for risk acknowledgement

Inspect the archive and review the findings first. Encrypted and limited-visibility containers may also require acknowledgement. Use `--allow-risky` in Terminal or `allow_risky: true` in an approved MCP tool call only when you choose to proceed. Path traversal and unsafe output remain blocked.

## The destination already exists

Choose a new file for creation or a new folder for extraction. The automation tools refuse replacement or merging. If a previous attempt failed, inspect its reported output before retrying with a different destination. Do not automatically delete an existing folder to make a command succeed.

## An encrypted archive fails

Check the password and whether the named environment variable reaches the process. Desktop applications do not necessarily inherit Terminal variables. Filenames encrypted inside an archive need the password before they can be listed. Some formats may not support the requested operation; a filename extension alone is not a guarantee of full support.

ZIP and 7z support encryption on creation; TAR.GZ does not. Filename encryption is only available for encrypted 7z output. Current password input supports printable ASCII characters, including spaces. Never include a password in a support report.

## The request is slow or stops

Large, damaged or solid-compressed archives can take time to inspect. Report pagination limits the response, not all scanning work. The MCP server runs requests serially and does not implement per-request cancellation notifications. Avoid repeatedly submitting the same write operation after a timeout; inspect the destination and client/server state first.

## Get help

Email [support@cozymacapps.com](mailto:support@cozymacapps.com) with the CozyZip version, macOS version, command/tool name, safe error code and the step that failed. Remove private paths and names. Do not include licence keys, passwords, full client configurations containing credentials or private archives unless support has specifically arranged a safe way to receive the necessary material.