npm package: @slimfile/cli
Description: Command-line interface for SlimFile file compression
Latest version: 1.1.3

# SlimFile CLI

Official command-line interface for the [SlimFile API](https://api.slim-file.com) — compress images, PDFs, and Office documents directly from your terminal with **up to 95% file size reduction without quality loss**.

[![npm version](https://img.shields.io/npm/v/@slimfile/cli)](https://www.npmjs.com/package/@slimfile/cli)
[![npm downloads](https://img.shields.io/npm/dm/@slimfile/cli)](https://www.npmjs.com/package/@slimfile/cli)
[![Node.js](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](https://nodejs.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## Table of Contents

- [Features](#features)
- [Supported Formats](#supported-formats)
- [Requirements](#requirements)
- [Installation](#installation)
- [Getting an API Key](#getting-an-api-key)
- [Quick Start](#quick-start)
- [Commands](#commands)
  - [login](#login)
  - [config](#config)
  - [compress](#compress)
  - [batch](#batch)
  - [stats](#stats)
  - [interactive](#interactive)
- [Examples](#examples)
- [Output](#output)
- [Configuration File](#configuration-file)
- [Error Handling](#error-handling)
- [Updating](#updating)
- [Uninstalling](#uninstalling)

---

## Features

- Reduce file sizes by **up to 95% without quality loss**
- Compress images, PDFs, PPTX, DOCX, and XLSX files from your terminal
- Batch compress entire folders using glob patterns
- Output as extracted files or as a ZIP archive
- View detailed usage statistics and analytics
- Interactive mode for guided compression without memorizing commands
- Stores your API key locally — no need to pass it on every command
- Works on macOS, Linux, and Windows

---

## Supported Formats

| Format | Extension |
|--------|-----------|
| JPEG | `.jpg`, `.jpeg` |
| PNG | `.png` |
| WebP | `.webp` |
| PDF | `.pdf` |
| PowerPoint | `.pptx` |
| Word | `.docx` |
| Excel | `.xlsx` |

> Note: Legacy formats (`.ppt`, `.doc`, `.xls`) are not supported. Convert them to the modern format first.

---

## Requirements

- Node.js **14.0.0 or higher**
- A SlimFile API key — [get one here](https://api.slim-file.com)

---

## Installation

Install the CLI globally so the `slimfile` command is available everywhere:

```bash
npm install -g @slimfile/cli
```

Verify the installation:

```bash
slimfile --version
```

---

## Getting an API Key

1. Create a free account at **[api.slim-file.com/signup](https://api.slim-file.com/signup)**
2. Log in at **[api.slim-file.com/signin](https://api.slim-file.com/signin)**
3. Navigate to **API Keys** in your dashboard
4. Click **Create API Key** and copy it

API keys start with `sk_` followed by a long string of characters.

---

## Quick Start

```bash
# 1. Install
npm install -g @slimfile/cli

# 2. Run setup — creates or logs into your account and generates an API key automatically
slimfile setup

# 3. Compress a file
slimfile compress photo.jpg

# Done! Your compressed file is saved as photo_compressed.jpg
```

---

## Commands

### `setup`

The recommended first command after installation. Creates a new account or logs into an existing one, then automatically generates and saves an API key — all from the terminal.

```bash
slimfile setup
```

You will be asked:
1. Do you have an account? (yes / no)
2. If **no** — enter your name, email, and password to create a free account
3. If **yes** — enter your email and password to log in
4. A `slimfile-cli` API key is automatically created and saved to `~/.slimfile/config.json`

After setup you are ready to compress files immediately.

> If you try to compress a file without running setup first, the CLI will automatically launch the setup flow for you.

---

### `login`

Log in to your SlimFile account. Required to use the `stats` command.

```bash
slimfile login
```

You will be prompted for your email and password. Your session token is saved locally — you only need to log in once.

---

### `config`

Manage your CLI configuration.

#### Set your API key

```bash
slimfile config set-key <apiKey>
```

```bash
slimfile config set-key sk_abc123...
```

Your API key is saved to `~/.slimfile/config.json` and used automatically on every compress and batch command.

#### Show current configuration

```bash
slimfile config show
```

Output:
```
SlimFile Configuration
────────────────────────────────────────
  API Key: sk_abc123...ef56
  API URL: https://api.slim-file.com
  Session: logged in
  Config:  /Users/you/.slimfile/config.json
```

---

### `compress`

Compress a single file.

```bash
slimfile compress <file> [options]
```

**Options:**

| Option | Description | Default |
|--------|-------------|---------|
| `-o, --output <path>` | Output file path | `<name>_compressed.<ext>` |
| `--quality <number>` | Compression quality (1–100) | `80` |

**Examples:**

```bash
# Compress an image (auto output name)
slimfile compress photo.jpg

# Compress with a custom output path
slimfile compress document.pdf -o smaller_document.pdf

# Compress with quality setting
slimfile compress banner.png --quality 70

# Compress a PowerPoint
slimfile compress presentation.pptx -o presentation_compressed.pptx

# Compress a Word document
slimfile compress report.docx

# Compress an Excel file
slimfile compress data.xlsx -o data_small.xlsx
```

**Output:**
```
✔ Compressed successfully
────────────────────────────────────────
  Input:   3.45 MB  photo.jpg
  Output:  890.2 KB  photo_compressed.jpg
  Saved:   2.58 MB (74.8% reduction)
```

> Note: PNG and WebP files are converted to JPEG after compression. All other formats keep their original extension.

---

### `batch`

Compress multiple files at once using a glob pattern.

```bash
slimfile batch <pattern> [options]
```

**Options:**

| Option | Description | Default |
|--------|-------------|---------|
| `-o, --output <path>` | Output directory or ZIP path | `./compressed` |
| `--zip` | Save as a ZIP archive instead of extracting | false |

**Examples:**

```bash
# Compress all JPGs in a folder (extracted to ./compressed/)
slimfile batch "./images/*.jpg"

# Compress all PDFs
slimfile batch "./documents/*.pdf"

# Compress multiple file types
slimfile batch "./files/*.{jpg,png,pdf,docx}"

# Compress all images in a folder and extract to a specific directory
slimfile batch "./assets/*.png" -o ./assets/compressed

# Compress files and save as a ZIP archive
slimfile batch "./images/*.jpg" --zip

# Compress files and save ZIP to a specific path
slimfile batch "./images/*.jpg" --zip -o compressed_images.zip
```

**Output:**
```
Found 5 file(s) to compress:
  • ./images/hero.jpg
  • ./images/about.jpg
  • ./images/team.jpg
  • ./images/banner.jpg
  • ./images/logo.png

✔ Batch compression complete
────────────────────────────────────────
  Files:  5 file(s)
  Input:  12.30 MB
  Output: 3.10 MB
  Saved:  9.20 MB (74.8% reduction)

  Extracted to: compressed/
```

> Always wrap glob patterns in quotes to prevent your shell from expanding them before the CLI receives them.

---

### `stats`

View your API usage statistics. Requires being logged in (`slimfile login`).

```bash
slimfile stats [options]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--detailed` | Show performance metrics, file type breakdown, and recent activity |

**Examples:**

```bash
# Basic stats
slimfile stats

# Detailed analytics
slimfile stats --detailed
```

**Basic output:**
```
SlimFile Usage Statistics
────────────────────────────────────────
  API Keys:          3
  Requests today:    12
  Files this month:  148
  Total files:       523
  Total saved:       1.23 GB
  Storage saved:     1.23 GB
  Avg compression:   68.4%
  Single compress:   310
  Batch compress:    213
```

**Detailed output adds:**
```
Performance
────────────────────────────────────────
  Avg processing:  320ms
  Fastest:         80ms
  Slowest:         2400ms

By File Type
────────────────────────────────────────
  image         310 files  72.1% avg compression
  pdf            98 files  45.3% avg compression
  pptx           75 files  61.8% avg compression
  docx           40 files  38.2% avg compression

Recent Activity
────────────────────────────────────────
  3/29/2026  hero.jpg                      74.8%  210ms
  3/29/2026  Q1_report.pdf                 42.1%  890ms
  3/28/2026  pitch_deck.pptx               63.4%  1200ms
```

---

### `interactive`

Start an interactive menu-driven mode. Useful if you don't want to memorize commands.

```bash
slimfile interactive

# Or just run slimfile with no arguments
slimfile
```

This launches a guided prompt where you can choose what to do:

```
  ╔═══════════════════════════╗
  ║     SlimFile CLI  v1.0    ║
  ╚═══════════════════════════╝
  Fast file compression for images, PDFs, and Office docs

? What would you like to do?
  📄  Compress a single file
  📦  Batch compress files
  📊  View usage statistics
  ⚙️   Show configuration
  ──────────────
  🚪  Exit
```

---

## Examples

### Compress a product image for a website

```bash
slimfile compress hero_image.png --quality 75 -o hero_image_web.jpg
```

### Compress all assets before deploying

```bash
slimfile batch "./public/images/*.{jpg,png}" -o ./public/images/compressed
```

### Compress and zip a set of PDFs to send via email

```bash
slimfile batch "./reports/*.pdf" --zip -o reports_compressed.zip
```

### Compress a large PowerPoint before sharing

```bash
slimfile compress big_presentation.pptx -o big_presentation_small.pptx
```

### Check how much storage you've saved this month

```bash
slimfile stats --detailed
```

---

## Output

By default, compressed files are saved alongside the original with `_compressed` added to the filename:

| Input | Output |
|-------|--------|
| `photo.jpg` | `photo_compressed.jpg` |
| `document.pdf` | `document_compressed.pdf` |
| `report.docx` | `report_compressed.docx` |
| `photo.png` | `photo_compressed.jpg` *(converted to JPEG)* |

Use `-o` to specify a custom output path:

```bash
slimfile compress photo.jpg -o optimized/photo.jpg
```

---

## Configuration File

The CLI stores your API key and session token in:

```
~/.slimfile/config.json
```

Example file:

```json
{
  "apiUrl": "https://api.slim-file.com",
  "apiKey": "sk_abc123...",
  "token": "eyJhbGci..."
}
```

- **apiKey** — used for all compress and batch commands
- **token** — your login session, used for the stats command
- **apiUrl** — the SlimFile API base URL (do not change unless self-hosting)

You can view these values at any time with:

```bash
slimfile config show
```

---

## Error Handling

| Error | Solution |
|-------|----------|
| `No API key set` | Run `slimfile config set-key YOUR_KEY` |
| `Not logged in` | Run `slimfile login` |
| `File not found` | Check the file path is correct |
| `Unsupported file type` | See [Supported Formats](#supported-formats) |
| `No files matched` | Check your glob pattern — wrap it in quotes |
| `Compression failed` | Check your API key is active in the dashboard |
| `401 Unauthorized` | Your API key may be expired or revoked |

---

## Updating

To update to the latest version:

```bash
npm update -g @slimfile/cli
```

Check your current version:

```bash
slimfile --version
```

---

## Uninstalling

```bash
npm uninstall -g @slimfile/cli
```

Your config file at `~/.slimfile/config.json` is not removed automatically. Delete it manually if needed:

```bash
rm -rf ~/.slimfile
```

---

## Links

- Website: [api.slim-file.com](https://api.slim-file.com)
- npm: [npmjs.com/package/@slimfile/cli](https://www.npmjs.com/package/@slimfile/cli)
- API Docs: [api.slim-file.com/documentation](https://api.slim-file.com)
- Issues: [github.com/ikaydreams-dev/slimfile-cli/issues](https://github.com/ikaydreams-dev/slimfile-cli/issues)

---

## License

MIT