https://github.com/paperfoot/realrestore-cli
AI image restoration CLI for Apple Silicon. 9 tasks, MPS/MLX backends, watermark removal. Agent-friendly.
https://github.com/paperfoot/realrestore-cli
agent-friendly ai-image-enhancement apple-silicon deblurring denoising diffusion-models image-processing image-restoration image-super-resolution image-upscaling macos metal-performance-shaders mlx mps photo-restoration python-cli pytorch real-esrgan rust-cli watermark-removal
Last synced: 25 days ago
JSON representation
AI image restoration CLI for Apple Silicon. 9 tasks, MPS/MLX backends, watermark removal. Agent-friendly.
- Host: GitHub
- URL: https://github.com/paperfoot/realrestore-cli
- Owner: paperfoot
- License: mit
- Created: 2026-03-29T04:50:04.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-17T20:43:08.000Z (26 days ago)
- Last Synced: 2026-04-17T22:13:50.956Z (26 days ago)
- Topics: agent-friendly, ai-image-enhancement, apple-silicon, deblurring, denoising, diffusion-models, image-processing, image-restoration, image-super-resolution, image-upscaling, macos, metal-performance-shaders, mlx, mps, photo-restoration, python-cli, pytorch, real-esrgan, rust-cli, watermark-removal
- Language: Python
- Size: 315 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# RealRestore CLI
**Restore degraded photos on Apple Silicon. Fast, local, agent-friendly.**
[](https://github.com/paperfoot/realrestore-cli/stargazers)
[](https://x.com/longevityboris)
[](https://www.rust-lang.org/)
[](https://www.python.org/)
[](https://developer.apple.com/metal/)
[](LICENSE)
---
A command-line tool for AI image restoration that runs entirely on your Mac. Handles 9 degradation types -- blur, noise, haze, rain, low light, compression artifacts, moire, lens flare, and reflections. Uses diffusion models through Metal (MPS) and MLX backends with float16 and quantization for speed and memory efficiency. Also removes invisible AI watermarks.
[Install](#install) | [How It Works](#how-it-works) | [Features](#features) | [Contributing](#contributing)
## Why This Exists
Most image restoration tools require cloud GPUs or NVIDIA hardware. If you have an M-series Mac, you have a capable ML accelerator sitting right there. RealRestore CLI wraps the [RealRestorer](https://github.com/yfyang007/RealRestorer) diffusion model with Apple Silicon optimizations so you can restore photos locally -- no uploads, no API keys, no cloud costs.
It also speaks JSON, has semantic exit codes, and self-describes its capabilities via `agent-info`. AI coding agents (Claude, Codex, Gemini) can discover and use it without documentation.
## Before vs After
```
Input: blurry, noisy, or degraded photo
|
realrestore restore
|
Output: sharp, clean, restored photo
```
RealRestore uses a FLUX-based diffusion pipeline to reconstruct detail that traditional sharpening filters cannot recover. The model generates plausible high-frequency content based on the degradation type, rather than simply amplifying existing pixels.
## Install
### Prerequisites
- macOS with Apple Silicon (M1/M2/M3/M4)
- Rust toolchain (`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`)
- Python 3.10+
### From Cargo
```bash
cargo install realrestore-cli
```
### From Source
```bash
git clone https://github.com/paperfoot/realrestore-cli
cd realrestore-cli
cargo build --release
```
### Setup (Downloads Models)
```bash
realrestore setup
```
This creates a Python virtual environment, installs dependencies, and downloads the RealRestorer model weights from Hugging Face. First run takes a few minutes depending on your connection.
## Quick Start
```bash
# Auto-detect degradation and restore
realrestore restore photo.jpg -o restored.jpg
# Target a specific degradation
realrestore restore blurry.png --task deblur --backend mps
# Fast mode (fewer steps + quantization)
realrestore restore photo.png --steps 10 --quantize int8 -o fast.png
# High quality mode
realrestore restore photo.png --quality high -o best.png
# Remove AI watermarks (StegaStamp, Tree-Ring, spectral)
realrestore watermark-remove ai_image.png -o clean.png
# Benchmark your hardware
realrestore benchmark --iterations 5
```
## How It Works
RealRestore CLI has two layers:
1. **Rust CLI** -- Handles argument parsing, output formatting (colored terminal or JSON), exit codes, and process management. Starts in milliseconds.
2. **Python inference backend** -- Runs the actual diffusion model via PyTorch and the `diffusers` library. Supports MPS (Metal), MLX, and CPU backends.
The CLI spawns the Python backend as a subprocess, passes parameters via command-line arguments, and captures structured JSON output. When piped, all output is machine-readable JSON. In a terminal, you get colored human-friendly output.
### Architecture
```
realrestore restore photo.jpg --task deblur --backend mps
|
[Rust CLI: parse args, validate input]
|
[Python engine: load model, run inference]
|
MPS (Metal) / MLX / CPU
|
[Output: restored image + metadata JSON]
```
## Features
### 9 Restoration Tasks
| Task | What It Fixes |
|------|--------------|
| `auto` | Auto-detect the degradation type |
| `deblur` | Motion blur, camera shake |
| `denoise` | Sensor noise, high ISO grain |
| `dehaze` | Fog, haze, atmospheric blur |
| `derain` | Rain streaks and water droplets |
| `low_light` | Underexposed, dark photos |
| `compression` | JPEG artifacts, banding |
| `moire` | Screen capture interference patterns |
| `lens_flare` | Lens flare and light artifacts |
| `reflection` | Glass reflections, unwanted reflections |
### Apple Silicon Optimization
- **MPS backend**: Metal Performance Shaders for GPU inference
- **MLX backend**: Apple's ML framework for optimized tensor ops
- **float16 inference**: Half the memory, faster computation
- **Attention slicing**: Process large images within memory limits
- **VAE slicing**: Decode high-resolution outputs without OOM
- **int8/int4 quantization**: Trade minimal quality for major speed gains
### AI Watermark Removal
Detects and removes invisible watermarks embedded by AI image generators:
- **StegaStamp**: Steganographic watermarks
- **Tree-Ring**: Diffusion-based watermarks
- **Spectral**: Frequency-domain watermarks
### Agent-Friendly Design
Built for AI coding agents following the [agent-cli-framework](https://github.com/paperfoot/agent-cli-framework) patterns:
```bash
# Self-describing capabilities
realrestore agent-info
# JSON output when piped
realrestore restore photo.jpg | jq .
# Semantic exit codes
# 0 = success, 1 = transient (retry), 2 = config error, 3 = bad input
```
### Tiling for High-Resolution Images
Process images larger than GPU memory allows:
```bash
realrestore restore large_photo.jpg --tile --tile-size 512 --tile-overlap 64
```
## Configuration
| Flag | Default | Description |
|------|---------|-------------|
| `--task` | `auto` | Restoration task (see table above) |
| `--backend` | `auto` | Inference backend: `mps`, `mlx`, `cpu` |
| `--quantize` | `none` | Quantization: `int8`, `int4`, `none` |
| `--steps` | `28` | Inference steps (more = higher quality) |
| `--seed` | `42` | Random seed for reproducibility |
| `--quality` | - | Preset: `fast`, `balanced`, `high` |
| `--tile` | `false` | Enable tiling for large images |
| `--tile-size` | `512` | Tile size in pixels |
| `--tile-overlap` | `64` | Tile overlap in pixels |
| `--json` | `false` | Force JSON output in terminal |
## Contributing
Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and guidelines.
Areas where help is especially useful:
- CUDA/ROCm backend support
- MLX performance improvements
- New restoration tasks
- Benchmarks on different Apple Silicon chips
## License
[MIT](LICENSE)
---
Built by [Boris Djordjevic](https://github.com/longevityboris) at [199 Biotechnologies](https://github.com/199-biotechnologies) | [Paperfoot AI](https://paperfoot.ai)
**If this is useful to you:**
[](https://github.com/paperfoot/realrestore-cli/stargazers)
[](https://x.com/longevityboris)