Cross-platform Zip/Unzip CLI

Common errors

• 'cross-zip' is not recognized as an internal or external command, operable program or batch file.

  cause The `cross-zip` command (or `cross-unzip`) is not found in your system's PATH. This typically happens if the package was installed locally and you are not calling it via `npx` or the `./node_modules/.bin` directory, or if a global installation failed.
  fix If installed locally, use `npx cross-zip` or run it from `$(npm bin)/cross-zip`. For global access, ensure it's installed globally with `npm install -g cross-zip-cli` and that your npm global bin directory is in your system's PATH.

• Error: Input directory does not exist: /path/to/nonexistent

  cause The source directory specified for zipping with `cross-zip` does not exist at the provided path.
  fix Verify that the input directory path is correct and that the directory actually exists before running the `cross-zip` command.

• Error: zip file not found: /path/to/nonexistent.zip

  cause The source zip file specified for unzipping with `cross-unzip` does not exist at the provided path.
  fix Verify that the input zip file path is correct and that the file actually exists before running the `cross-unzip` command.

• Error: Cannot create zip file: EACCES: permission denied, open '/path/to/output.zip'

  cause The user executing the command does not have sufficient write permissions to create the output zip file or directory at the specified destination.
  fix Change the output directory to one where the current user has write permissions, or adjust the file system permissions for the target directory.

Warnings

• gotcha When installing, `cross-zip-cli` is primarily designed for global installation (`npm install -g cross-zip-cli`) or execution via `npx` (e.g., `npx cross-zip-cli`). If installed locally without using `npx`, the commands may not be directly available in your shell's PATH without specifying `./node_modules/.bin/cross-zip`.
  Fix: Always install globally with `npm install -g cross-zip-cli` or use `npx cross-zip` (after a local `npm install cross-zip-cli`) to ensure commands are executable.
• gotcha Paths containing spaces must be enclosed in double quotes (e.g., `"./my folder/data"`) when passed as arguments to `cross-zip` or `cross-unzip`, especially on Windows, to prevent misinterpretation of the arguments.
  Fix: Quote any path arguments that contain spaces or special characters: `cross-zip "./path with spaces/input" "./path with spaces/output.zip"`.
• gotcha The `cross-zip-cli` tool currently does not provide a progress indicator during zipping or unzipping operations. For very large directories or files, the command may appear to hang, leading to uncertainty about its status.
  Fix: Monitor the file system for changes (e.g., new zip file appearing, target directory growing) or run in a background process if non-blocking execution is required. Consider piping output to a log file for long operations.
• gotcha By default, `cross-zip` will overwrite an existing destination zip file without prompting. This can lead to unintended data loss if the target file path is already in use.
  Fix: Ensure your build scripts or manual commands check for the existence of the destination zip file (e.g., using `test -f file.zip || cross-zip ...`) or use temporary filenames to prevent accidental overwrites.

Install

• npm install cross-zip-cli npm
• yarn add cross-zip-cli yarn
• pnpm add cross-zip-cli pnpm

Imports

• cross-zip
  wrong:

  import { crossZip } from 'cross-zip-cli';

  correct:

  n/a (CLI executable)

  This package provides command-line executables ('cross-zip', 'cross-unzip') which are invoked directly from the shell or npm scripts. It does not export JavaScript symbols for programmatic use via `import` or `require`.
• cross-unzip
  wrong:

  const crossUnzip = require('cross-zip-cli').unzip;

  correct:

  n/a (CLI executable)

  The decompression functionality is accessed via the 'cross-unzip' command in your terminal after global installation or via npx, not through JavaScript imports or CommonJS `require` calls.
• Package Root
  wrong:

  import crossZipCli from 'cross-zip-cli';

  correct:

  n/a (CLI package)

  Attempting to import the root of the 'cross-zip-cli' package will result in an empty or undefined module, as its purpose is solely to provide executable scripts for the command line.

Quickstart

This quickstart demonstrates how to install `cross-zip-cli` and then use its `cross-zip` and `cross-unzip` commands within `npm` scripts to create a test directory, archive it, and then extract its contents, ensuring cross-platform compatibility.

{}
{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "install-cli": "npm install -g cross-zip-cli",
    "create-test-dir": "mkdir -p ./temp/data && echo 'Hello, world!' > ./temp/data/hello.txt && echo 'Another file.' > ./temp/data/another.txt",
    "zip-data": "cross-zip ./temp/data ./temp/archive.zip",
    "unzip-data": "cross-unzip ./temp/archive.zip ./temp/extracted",
    "clean": "rm -rf ./temp"
  }
}
```

```bash
# Install the CLI globally (or use npx for local execution)
npm run install-cli

# Create a dummy directory with files
npm run create-test-dir

# Zip the 'data' directory into 'archive.zip'
npm run zip-data

# Unzip 'archive.zip' into a new 'extracted' directory
npm run unzip-data

# Clean up temporary files
npm run clean
```