{"id":16977,"library":"cross-zip-cli","title":"Cross-platform Zip/Unzip CLI","description":"cross-zip-cli is a command-line interface wrapper for the `cross-zip` library, designed to provide consistent cross-platform directory zipping and unzipping capabilities. It exposes two main commands: `cross-zip` for compression and `cross-unzip` for decompression. This tool is particularly valuable for developers writing `npm` scripts or other automated build processes that need to function identically across Windows, macOS, and Linux environments, abstracting away the underlying operating system's native archiving utilities. The current stable version is 1.0.0, and it appears to be in a maintenance state with no recent updates since 2021. Its primary differentiator is its focus on simplifying cross-platform archival tasks within automated workflows, ensuring reliability and compatibility regardless of the host OS.","status":"maintenance","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/jprichardson/cross-zip-cli","tags":["javascript","cli","linux","mac","osx","unzip","windows","zip"],"install":[{"cmd":"npm install cross-zip-cli","lang":"bash","label":"npm"},{"cmd":"yarn add cross-zip-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add cross-zip-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core zipping/unzipping logic is provided by this underlying library.","package":"cross-zip","optional":false}],"imports":[{"note":"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`.","wrong":"import { crossZip } from 'cross-zip-cli';","symbol":"cross-zip","correct":"n/a (CLI executable)"},{"note":"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.","wrong":"const crossUnzip = require('cross-zip-cli').unzip;","symbol":"cross-unzip","correct":"n/a (CLI executable)"},{"note":"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.","wrong":"import crossZipCli from 'cross-zip-cli';","symbol":"Package Root","correct":"n/a (CLI package)"}],"quickstart":{"code":"{}\n{\n  \"name\": \"my-project\",\n  \"version\": \"1.0.0\",\n  \"scripts\": {\n    \"install-cli\": \"npm install -g cross-zip-cli\",\n    \"create-test-dir\": \"mkdir -p ./temp/data && echo 'Hello, world!' > ./temp/data/hello.txt && echo 'Another file.' > ./temp/data/another.txt\",\n    \"zip-data\": \"cross-zip ./temp/data ./temp/archive.zip\",\n    \"unzip-data\": \"cross-unzip ./temp/archive.zip ./temp/extracted\",\n    \"clean\": \"rm -rf ./temp\"\n  }\n}\n```\n\n```bash\n# Install the CLI globally (or use npx for local execution)\nnpm run install-cli\n\n# Create a dummy directory with files\nnpm run create-test-dir\n\n# Zip the 'data' directory into 'archive.zip'\nnpm run zip-data\n\n# Unzip 'archive.zip' into a new 'extracted' directory\nnpm run unzip-data\n\n# Clean up temporary files\nnpm run clean\n```","lang":"bash","description":"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."},"warnings":[{"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.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Quote any path arguments that contain spaces or special characters: `cross-zip \"./path with spaces/input\" \"./path with spaces/output.zip\"`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","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.","error":"'cross-zip' is not recognized as an internal or external command, operable program or batch file."},{"fix":"Verify that the input directory path is correct and that the directory actually exists before running the `cross-zip` command.","cause":"The source directory specified for zipping with `cross-zip` does not exist at the provided path.","error":"Error: Input directory does not exist: /path/to/nonexistent"},{"fix":"Verify that the input zip file path is correct and that the file actually exists before running the `cross-unzip` command.","cause":"The source zip file specified for unzipping with `cross-unzip` does not exist at the provided path.","error":"Error: zip file not found: /path/to/nonexistent.zip"},{"fix":"Change the output directory to one where the current user has write permissions, or adjust the file system permissions for the target directory.","cause":"The user executing the command does not have sufficient write permissions to create the output zip file or directory at the specified destination.","error":"Error: Cannot create zip file: EACCES: permission denied, open '/path/to/output.zip'"}],"ecosystem":"npm","meta_description":null}