@pz4l/tinyimg-cli 0.0.0

package/README.md

@@ -0,0 +1,227 @@
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+# tinyimg-cli
+
+Smart image compression CLI tool based on TinyPNG with multi-API key management, intelligent caching, and concurrent compression.
+
+## Features
+
+- **Batch Compression** - Supports files, directories, and glob patterns
+- **Multi-API Key Management** - Smart rotation strategies to maximize free quota usage
+- **Intelligent Caching** - MD5-based permanent cache to avoid redundant compression
+- **Concurrency Control** - Configurable parallel compression tasks
+- **Multiple Key Strategies** - Three modes: random, round-robin, priority
+
+## Installation
+
+### Global Installation (Recommended)
+
+```bash
+# Using npm
+npm install -g @pz4l/tinyimg-cli
+
+# Using pnpm
+pnpm add -g tinyimg-cli
+
+# Using yarn
+yarn global add tinyimg-cli
+```
+
+### Local Installation
+
+```bash
+# Using npm
+npm install -D @pz4l/tinyimg-cli
+
+# Using pnpm
+pnpm add -D tinyimg-cli
+
+# Using yarn
+yarn add -D tinyimg-cli
+```
+
+## Quick Start
+
+```bash
+# Add API Key
+tinyimg key add YOUR_TINYPNG_API_KEY
+
+# Compress all images in current directory
+tinyimg *.png *.jpg
+
+# Compress specified directory
+tinyimg ./images/
+```
+
+## Usage
+
+### Basic Compression Command
+
+```bash
+tinyimg [options] <input...>
+```
+
+**Input parameters support:**
+
+- Single file: `image.png`
+- Multiple files: `image1.png image2.jpg`
+- Directory: `./images/`
+- Glob pattern: `./assets/**/*.png`
+
+### Command Options
+
+| Option                    | Description                                                 | Default  |
+| ------------------------- | ----------------------------------------------------------- | -------- |
+| `-o, --output <dir>`      | Specify output directory                                    | In-place |
+| `-k, --key <key>`         | Specify API Key (higher priority than env variable)         | -        |
+| `-m, --mode <mode>`       | Key usage strategy: `random` \| `round-robin` \| `priority` | `random` |
+| `-p, --parallel <number>` | Concurrency limit                                           | `8`      |
+| `-c, --cache`             | Enable cache                                                | `true`   |
+| `--no-cache`              | Disable cache                                               | -        |
+| `-h, --help`              | Show help information                                       | -        |
+
+### Key Management Commands
+
+```bash
+# Add API Key
+tinyimg key add <key>
+
+# Remove API Key (interactive selection)
+tinyimg key remove
+
+# Remove specified API Key
+tinyimg key remove <key>
+
+# List all API Keys and quota information
+tinyimg key
+```
+
+**Key Display Format:** API keys are displayed in a masked format (first 4 chars + last 4 chars, e.g., `abcd****efgh`) for easy identification while protecting sensitive information.
+
+## Usage Examples
+
+### Compress Single File
+
+```bash
+tinyimg photo.png
+```
+
+### Compress Multiple Files
+
+```bash
+tinyimg image1.png image2.jpg image3.jpeg
+```
+
+### Compress Entire Directory
+
+```bash
+tinyimg ./assets/images/
+```
+
+### Use Glob Pattern
+
+```bash
+# Compress all PNG files
+tinyimg "./src/**/*.png"
+
+# Compress multiple formats
+tinyimg "./assets/**/*.{png,jpg,jpeg}"
+```
+
+### Specify Output Directory
+
+```bash
+# Compress to dist directory, preserve directory structure
+tinyimg ./assets/ -o ./dist/
+
+# Compress to specified directory
+tinyimg photo.png -o ./compressed/
+```
+
+### Use Specific Key Strategy
+
+```bash
+# Round-robin mode (evenly distribute quota)
+tinyimg ./images/ -m round-robin
+
+# Priority mode (prefer specified key)
+tinyimg ./images/ -m priority
+
+# Random mode (default)
+tinyimg ./images/ -m random
+```
+
+### Adjust Concurrency
+
+```bash
+# Lower concurrency (suitable for unstable network)
+tinyimg ./images/ -p 4
+
+# Higher concurrency (suitable for high-performance network)
+tinyimg ./images/ -p 16
+```
+
+### Disable Cache
+
+```bash
+# Force re-compression of all images
+tinyimg ./images/ --no-cache
+```
+
+### Specify API Key
+
+```bash
+# Use specific key for compression (highest priority)
+tinyimg ./images/ -k YOUR_API_KEY
+```
+
+## Environment Variables
+
+```bash
+# Set API Keys (multiple keys separated by comma)
+export TINYPNG_KEYS="key1,key2,key3"
+
+# Run compression command
+tinyimg ./images/
+```
+
+## Cache System
+
+TinyImg uses a two-level cache system:
+
+1. **Project-level cache** - `node_modules/.tinyimg_cache/` (priority)
+2. **Global cache** - `~/.tinyimg/cache/` (fallback)
+
+Cache is based on MD5 hash of file content. Files with same content will hit cache regardless of location.
+
+## Supported Formats
+
+- **PNG** - Including transparent PNG
+- **JPG/JPEG** - All JPEG variants
+
+> Note: TinyPNG does not support WebP, AVIF, SVG, or other formats.
+
+## Quota Management
+
+TinyPNG free tier provides 500 compressions per month. TinyImg maximizes utilization through:
+
+- **Multi-Key Management** - Configure multiple keys for automatic rotation
+- **Intelligent Caching** - Avoid re-compressing identical content
+- **Quota Monitoring** - Real-time display of remaining quota for each key
+
+## Error Handling
+
+| Error Type                  | Description                    | Solution                                |
+| --------------------------- | ------------------------------ | --------------------------------------- |
+| `NoValidKeysError`          | No valid API Key configured    | Run `tinyimg key add <key>` to add key  |
+| `AllKeysExhaustedError`     | All keys quota exhausted       | Add new key                             |
+| `AllCompressionFailedError` | All compression methods failed | Check network connection and API status |
+
+## Related Packages
+
+- [@pz4l/tinyimg-core](https://github.com/pzehrel/tinyimg/tree/main/packages/tinyimg-core) - Core compression library
+- [@pz4l/tinyimg-unplugin](https://github.com/pzehrel/tinyimg/tree/main/packages/tinyimg-unplugin) - Vite/Webpack/Rolldown plugin
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,227 @@
+[English](README.md) | 简体中文
+
+# tinyimg-cli
+
+基于 TinyPNG 的智能图片压缩 CLI 工具，支持多 API Key 管理、智能缓存和并发压缩。
+
+## 特性
+
+- **批量压缩** - 支持文件、目录和 glob 模式
+- **多 API Key 管理** - 支持多个 API Key 管理
+- **智能缓存** - 基于 MD5 的永久缓存，避免重复压缩
+- **并发控制** - 可配置的并行压缩任务数
+- **多种 Key 策略** - random、round-robin、priority 三种模式
+
+## 安装
+
+### 全局安装（推荐）
+
+```bash
+# 使用 npm
+npm install -g @pz4l/tinyimg-cli
+
+# 使用 pnpm
+pnpm add -g tinyimg-cli
+
+# 使用 yarn
+yarn global add tinyimg-cli
+```
+
+### 项目本地安装
+
+```bash
+# 使用 npm
+npm install -D @pz4l/tinyimg-cli
+
+# 使用 pnpm
+pnpm add -D tinyimg-cli
+
+# 使用 yarn
+yarn add -D tinyimg-cli
+```
+
+## 快速开始
+
+```bash
+# 添加 API Key
+tinyimg key add YOUR_TINYPNG_API_KEY
+
+# 压缩当前目录所有图片
+tinyimg *.png *.jpg
+
+# 压缩指定目录
+tinyimg ./images/
+```
+
+## 使用方法
+
+### 基本压缩命令
+
+```bash
+tinyimg [options] <input...>
+```
+
+**输入参数支持：**
+
+- 单个文件：`image.png`
+- 多个文件：`image1.png image2.jpg`
+- 目录：`./images/`
+- Glob 模式：`./assets/**/*.png`
+
+### 命令选项
+
+| 选项                      | 说明                                                  | 默认值   |
+| ------------------------- | ----------------------------------------------------- | -------- |
+| `-o, --output <dir>`      | 指定输出目录                                          | 原地覆盖 |
+| `-k, --key <key>`         | 指定 API Key（优先级高于环境变量）                    | -        |
+| `-m, --mode <mode>`       | Key 使用策略：`random` \| `round-robin` \| `priority` | `random` |
+| `-p, --parallel <number>` | 并发数限制                                            | `8`      |
+| `-c, --cache`             | 启用缓存                                              | `true`   |
+| `--no-cache`              | 禁用缓存                                              | -        |
+| `-h, --help`              | 显示帮助信息                                          | -        |
+
+### Key 管理命令
+
+```bash
+# 添加 API Key
+tinyimg key add <key>
+
+# 移除 API Key（交互式选择）
+tinyimg key remove
+
+# 移除指定 API Key
+tinyimg key remove <key>
+
+# 列出所有 API Key 及额度信息
+tinyimg key
+```
+
+**Key 显示格式：** API Key 会以脱敏方式显示（前 4 位 + 后 4 位，如 `abcd****efgh`），方便识别同时保护敏感信息。
+
+## 使用示例
+
+### 压缩单个文件
+
+```bash
+tinyimg photo.png
+```
+
+### 压缩多个文件
+
+```bash
+tinyimg image1.png image2.jpg image3.jpeg
+```
+
+### 压缩整个目录
+
+```bash
+tinyimg ./assets/images/
+```
+
+### 使用 Glob 模式
+
+```bash
+# 压缩所有 PNG 文件
+tinyimg "./src/**/*.png"
+
+# 压缩多种格式
+tinyimg "./assets/**/*.{png,jpg,jpeg}"
+```
+
+### 指定输出目录
+
+```bash
+# 压缩到 dist 目录，保持目录结构
+tinyimg ./assets/ -o ./dist/
+
+# 压缩到指定目录
+tinyimg photo.png -o ./compressed/
+```
+
+### 使用特定 Key 策略
+
+```bash
+# 轮询模式（均匀分配额度）
+tinyimg ./images/ -m round-robin
+
+# 优先级模式（优先使用指定 key）
+tinyimg ./images/ -m priority
+
+# 随机模式（默认）
+tinyimg ./images/ -m random
+```
+
+### 调整并发数
+
+```bash
+# 降低并发数（适合网络不稳定环境）
+tinyimg ./images/ -p 4
+
+# 提高并发数（适合高性能网络）
+tinyimg ./images/ -p 16
+```
+
+### 禁用缓存
+
+```bash
+# 强制重新压缩所有图片
+tinyimg ./images/ --no-cache
+```
+
+### 指定 API Key
+
+```bash
+# 使用特定 key 进行压缩（优先级最高）
+tinyimg ./images/ -k YOUR_API_KEY
+```
+
+## 环境变量
+
+```bash
+# 设置 API Keys（多个 key 用逗号分隔）
+export TINYPNG_KEYS="key1,key2,key3"
+
+# 运行压缩命令
+tinyimg ./images/
+```
+
+## 缓存系统
+
+TinyImg 使用两级缓存系统：
+
+1. **项目级缓存** - `node_modules/.tinyimg_cache/`（优先）
+2. **全局缓存** - `~/.tinyimg/cache/`（后备）
+
+缓存基于文件内容的 MD5 哈希，相同内容的文件无论位置如何都会命中缓存。
+
+## 支持格式
+
+- **PNG** - 包括透明 PNG
+- **JPG/JPEG** - 所有 JPEG 变体
+
+> 注意：TinyPNG 不支持 WebP、AVIF、SVG 等格式。
+
+## 额度管理
+
+TinyImg 通过以下方式优化额度使用：
+
+- **多 Key 管理** - 配置多个 key 自动轮换
+- **智能缓存** - 避免重复压缩相同内容
+- **额度监控** - 实时显示各 key 的剩余额度
+
+## 错误处理
+
+| 错误类型                    | 说明                   | 解决方案                              |
+| --------------------------- | ---------------------- | ------------------------------------- |
+| `NoValidKeysError`          | 没有配置有效的 API Key | 运行 `tinyimg key add <key>` 添加 key |
+| `AllKeysExhaustedError`     | 所有 key 额度已用完    | 添加新 key                            |
+| `AllCompressionFailedError` | 所有压缩方式失败       | 检查网络连接和 API 状态               |
+
+## 相关包
+
+- [@pz4l/tinyimg-core](https://github.com/pzehrel/tinyimg/tree/main/packages/tinyimg-core) - 核心压缩库
+- [@pz4l/tinyimg-unplugin](https://github.com/pzehrel/tinyimg/tree/main/packages/tinyimg-unplugin) - Vite/Webpack/Rolldown 插件
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+//#region src/cli.d.ts
+declare function main(): Promise<void>;
+//#endregion
+export { main };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/cli.ts"],"mappings":";iBAwEsB,IAAA,CAAA,GAAI,OAAA"}