Unofficial command line tool for the Tinify API, the API behind TinyPNG and TinyJPG.
It compresses AVIF, WebP, JPEG, and PNG files from a terminal, with optional conversion to WebP, AVIF, JPEG, PNG, or the smallest format Tinify returns.
Tinify provides official API clients, but this project focuses on a small CLI workflow:
- Store an API key locally once.
- Compress one image, many images, or a directory.
- Convert oversized images to WebP or AVIF without writing a script.
- Keep default behavior conservative: no overwrite unless explicitly requested.
npm install -g @yigemo/tinify-cliFor local development from this repository:
npm install
npm run build
npm linkSource files live in src/*.ts. The published CLI runs compiled files from dist/src, and declaration files are generated for editors and downstream TypeScript users.
Store your Tinify API key:
tinify login --key YOUR_API_KEYCompress a single image without changing its format:
tinify image.pngCreate a WebP copy:
tinify image.png --format webpCompress all supported images in a directory:
tinify public/images --recursive --out-dir dist/imagesOverwrite originals only when you really mean it:
tinify public/images --recursive --overwritePreview output paths without calling the API:
tinify public/images --recursive --format webp --dry-runtinify login [--key <key>] Store an API key in local config
tinify logout Remove the stored API key
tinify config Show config path, key status, and cached monthly usage
tinify usage Show cached monthly Tinify API usage
tinify <file-or-dir...> [flags] Compress images
-r, --recursive Walk directories recursively
-o, --out-dir <dir> Write files under another directory
--format <format> same, webp, avif, jpeg, png, or smallest
--suffix <text> Add a suffix before the output extension
--overwrite Replace source files; only allowed with --format same
--background <color> white, black, or #rrggbb for JPEG transparency fills
--key <key> Use this API key for the current command
--config <path> Use a custom config file
--dry-run Print planned outputs without API calls
--quiet Print only errors
--help Show help
--version Show version
TINIFY_API_KEY can also be used instead of storing a key. Environment variables and --key do not get written to disk unless you run tinify login.
By default, the CLI stores config at:
~/.config/tinify-cli/config.json
The config file is written with 0600 permissions when the platform supports it. API keys are never printed in full.
Tinify's Developer API includes 500 free compressions per month. After a successful API call, Tinify returns a Compression-Count response header with the number of compressions used in the current calendar month. This CLI caches the latest value and shows it in command output.
tinify usagetinify usage does not call the API. It displays the last count observed from a successful compression, including the estimated remaining free monthly quota and the masked API key that produced the cached count.
The Tinify HTTP API returns a Compression-Count response header with the number of compressions made in the current calendar month. This CLI records the latest value it sees after successful API calls, but it does not call a separate usage endpoint because Tinify does not expose one in the HTTP API.
Converting formats may count as an additional compression depending on the Tinify API operation. Check Tinify's official documentation for quota and billing behavior.
The CLI intentionally stores one API key by default. Multiple keys with automatic switching can be useful for separate projects or teams, but it can also obscure which account is being billed and make quota behavior harder to audit. Prefer explicit configs today, for example tinify --config ./project-a.tinify.json ..., or TINIFY_API_KEY=... tinify ....
MIT