# Tinypng CLI: Efficient Image Compression Tool

Tinypng CLI is a command-line tool that utilizes the **[Tinypng.com](https://tinypng.com/)** web version to compress images and support multiple format conversions and archive operations.
<img src="https://img.shields.io/npm/v/@julytian/tinypng-cli?style=flat-square" alt="npm version" />

🇨🇳 <a href="./README.zh-CN.md">查看中文版介绍</a>

## Features

- Supports multiple image formats: png, jpg, jpeg, webp
- Convenient compression methods: Single image, entire folder, or archive
- Flexible image format conversion: Mutual conversion between png, jpg, jpeg, webp
- Archive decompression: Supports tar, zip, tgz formats
- Packaging of compressed images: Generate tar, zip, tgz formats for archives

## Requirements

- **Node.js ≥ 24** (v3.x is ESM-only and relies on native `fetch`, `node:util.parseArgs`, `fs.glob`, and import attributes)

> Need older runtime support? Stay on the `v2.x` releases (`npm i @julytian/tinypng-cli@2`).

## Installation

```shell
# npm
npm i @julytian/tinypng-cli -g

# yarn
yarn i @julytian/tinypng-cli -g

# pnpm
pnpm i @julytian/tinypng-cli -g
```

## Quick Start

```shell
$ tinypng <file> [options]
# Help information
$ tinypng --help
# Version information
$ tinypng --version
# Language setting for output (zh, en)
$ tinypng -l zh
# Compress a single image
$ tinypng a.png
# Compress a single image and convert png to jpeg
$ tinypng a.png -c jpeg
# Compress a single image and generate zip archive
$ tinypng a.png -z
# Compress a single image and generate tar archive
$ tinypng a.png -z tar
# Compress images in directory a
$ tinypng a
# Recursively traverse directory a, compress all images in it
$ tinypng a -r
# Compress images in the directory and generate a zip archive
$ tinypng a -z
# Compress all images in the directory and generate a zip archive
$ tinypng a -r -z
# Compress all images in the directory and generate a tgz archive
$ tinypng a -r -z tgz
# Decompress a zip archive and compress images in it
$ tinypng a.zip
# Decompress a zip archive and compress images in it, and regenerate a zip archive
$ tinypng a.zip -z
# Decompress a zip archive and compress images in it, and regenerate a tar archive
$ tinypng a.zip -z tar
```

## Options

- -h, --help: Show help information.
- -v, --version: Show version number.
- -z, --zip : Generate archive of the specified format (zip, tar, tgz).
- -c, --convert : Convert images to the specified format (png, jpg, jpeg, webp).
- -r, --recursive: Recursively traverse folders.
- -l, --language : Set the output language (zh, en).

## Examples

```shell
# Compress the image named "a.png"
$ tinypng a.png

# Compress the image named "a.png" and convert it to jpeg
$ tinypng a.png -c jpeg

# Compress the image named "a.png" and generate a zip archive
$ tinypng a.png -z

# Compress all images in the folder named "images"
$ tinypng images -r

# Decompress the zip archive named "images.zip" and compress the images inside
$ tinypng images.zip
```

## v3 Highlights

Tinypng CLI v3 is a full rewrite that keeps the CLI surface 100% compatible while modernizing the internals:

- **ESM-only single-file bundle** (`dist/index.mjs`, ~10 KB minified) built with [tsdown](https://github.com/sxzz/tsdown).
- **Functional pipeline** — 5 stages (`resolveInputs → uploadImages → downloadResults → renderReport → maybeArchive`) replace the legacy god class.
- **Concurrent uploads** via `p-limit` (default 6, bounded by the TinyPNG backend).
- **Native Node APIs** replace `minimist`, `fs-extra`, `fast-glob`, `mime-types`, `nanospinner`, etc. Runtime dependencies dropped from 16 → 8.
- **i18n with import attributes** — translations are inlined at build time, no more filesystem lookups at startup.
- **82 unit + e2e tests** (`node:test` + `undici.MockAgent`), strict TypeScript 6 (`exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`).
- **Better exit codes** — `0` (ok), `1` (all failed), `2` (archive failed), `64` (bad args), `74` (IO error), `70` (unknown).

See [CHANGELOG.md](./CHANGELOG.md) for the full migration notes.

## License

This project is licensed under the [MIT License](https://github.com/julytian/tinypng-cli/blob/master/LICENSE).