{"id":48963798,"url":"https://github.com/paperfoot/realrestore-cli","last_synced_at":"2026-04-18T03:04:17.399Z","repository":{"id":347709155,"uuid":"1195004016","full_name":"paperfoot/realrestore-cli","owner":"paperfoot","description":"AI image restoration CLI for Apple Silicon. 9 tasks, MPS/MLX backends, watermark removal. Agent-friendly.","archived":false,"fork":false,"pushed_at":"2026-04-17T20:43:08.000Z","size":323,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-17T22:13:50.956Z","etag":null,"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"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paperfoot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-29T04:50:04.000Z","updated_at":"2026-04-17T20:43:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/paperfoot/realrestore-cli","commit_stats":null,"previous_names":["199-biotechnologies/realrestore-cli","paperfoot/realrestore-cli"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/paperfoot/realrestore-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Frealrestore-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Frealrestore-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Frealrestore-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Frealrestore-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paperfoot","download_url":"https://codeload.github.com/paperfoot/realrestore-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Frealrestore-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31954738,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-04-18T03:04:14.231Z","updated_at":"2026-04-18T03:04:17.391Z","avatar_url":"https://github.com/paperfoot.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# RealRestore CLI\n\n**Restore degraded photos on Apple Silicon. Fast, local, agent-friendly.**\n\n\u003cbr /\u003e\n\n[![Star this repo](https://img.shields.io/github/stars/paperfoot/realrestore-cli?style=for-the-badge\u0026logo=github\u0026label=%E2%AD%90%20Star%20this%20repo\u0026color=yellow)](https://github.com/paperfoot/realrestore-cli/stargazers)\n\u0026nbsp;\u0026nbsp;\n[![Follow @longevityboris](https://img.shields.io/badge/Follow_%40longevityboris-000000?style=for-the-badge\u0026logo=x\u0026logoColor=white)](https://x.com/longevityboris)\n\n\u003cbr /\u003e\n\n[![Rust](https://img.shields.io/badge/Rust-000000?style=for-the-badge\u0026logo=rust\u0026logoColor=white)](https://www.rust-lang.org/)\n[![Python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white)](https://www.python.org/)\n[![Apple Silicon](https://img.shields.io/badge/Apple%20Silicon-000000?style=for-the-badge\u0026logo=apple\u0026logoColor=white)](https://developer.apple.com/metal/)\n[![License: MIT](https://img.shields.io/badge/MIT-green?style=for-the-badge)](LICENSE)\n\n---\n\nA 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.\n\n[Install](#install) | [How It Works](#how-it-works) | [Features](#features) | [Contributing](#contributing)\n\n\u003c/div\u003e\n\n## Why This Exists\n\nMost 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.\n\nIt 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.\n\n## Before vs After\n\n```\nInput: blurry, noisy, or degraded photo\n                    |\n          realrestore restore\n                    |\nOutput: sharp, clean, restored photo\n```\n\nRealRestore 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.\n\n## Install\n\n### Prerequisites\n\n- macOS with Apple Silicon (M1/M2/M3/M4)\n- Rust toolchain (`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`)\n- Python 3.10+\n\n### From Cargo\n\n```bash\ncargo install realrestore-cli\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/paperfoot/realrestore-cli\ncd realrestore-cli\ncargo build --release\n```\n\n### Setup (Downloads Models)\n\n```bash\nrealrestore setup\n```\n\nThis 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.\n\n## Quick Start\n\n```bash\n# Auto-detect degradation and restore\nrealrestore restore photo.jpg -o restored.jpg\n\n# Target a specific degradation\nrealrestore restore blurry.png --task deblur --backend mps\n\n# Fast mode (fewer steps + quantization)\nrealrestore restore photo.png --steps 10 --quantize int8 -o fast.png\n\n# High quality mode\nrealrestore restore photo.png --quality high -o best.png\n\n# Remove AI watermarks (StegaStamp, Tree-Ring, spectral)\nrealrestore watermark-remove ai_image.png -o clean.png\n\n# Benchmark your hardware\nrealrestore benchmark --iterations 5\n```\n\n## How It Works\n\nRealRestore CLI has two layers:\n\n1. **Rust CLI** -- Handles argument parsing, output formatting (colored terminal or JSON), exit codes, and process management. Starts in milliseconds.\n2. **Python inference backend** -- Runs the actual diffusion model via PyTorch and the `diffusers` library. Supports MPS (Metal), MLX, and CPU backends.\n\nThe 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.\n\n### Architecture\n\n```\nrealrestore restore photo.jpg --task deblur --backend mps\n        |\n  [Rust CLI: parse args, validate input]\n        |\n  [Python engine: load model, run inference]\n        |\n    MPS (Metal) / MLX / CPU\n        |\n  [Output: restored image + metadata JSON]\n```\n\n## Features\n\n### 9 Restoration Tasks\n\n| Task | What It Fixes |\n|------|--------------|\n| `auto` | Auto-detect the degradation type |\n| `deblur` | Motion blur, camera shake |\n| `denoise` | Sensor noise, high ISO grain |\n| `dehaze` | Fog, haze, atmospheric blur |\n| `derain` | Rain streaks and water droplets |\n| `low_light` | Underexposed, dark photos |\n| `compression` | JPEG artifacts, banding |\n| `moire` | Screen capture interference patterns |\n| `lens_flare` | Lens flare and light artifacts |\n| `reflection` | Glass reflections, unwanted reflections |\n\n### Apple Silicon Optimization\n\n- **MPS backend**: Metal Performance Shaders for GPU inference\n- **MLX backend**: Apple's ML framework for optimized tensor ops\n- **float16 inference**: Half the memory, faster computation\n- **Attention slicing**: Process large images within memory limits\n- **VAE slicing**: Decode high-resolution outputs without OOM\n- **int8/int4 quantization**: Trade minimal quality for major speed gains\n\n### AI Watermark Removal\n\nDetects and removes invisible watermarks embedded by AI image generators:\n- **StegaStamp**: Steganographic watermarks\n- **Tree-Ring**: Diffusion-based watermarks\n- **Spectral**: Frequency-domain watermarks\n\n### Agent-Friendly Design\n\nBuilt for AI coding agents following the [agent-cli-framework](https://github.com/paperfoot/agent-cli-framework) patterns:\n\n```bash\n# Self-describing capabilities\nrealrestore agent-info\n\n# JSON output when piped\nrealrestore restore photo.jpg | jq .\n\n# Semantic exit codes\n# 0 = success, 1 = transient (retry), 2 = config error, 3 = bad input\n```\n\n### Tiling for High-Resolution Images\n\nProcess images larger than GPU memory allows:\n\n```bash\nrealrestore restore large_photo.jpg --tile --tile-size 512 --tile-overlap 64\n```\n\n## Configuration\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--task` | `auto` | Restoration task (see table above) |\n| `--backend` | `auto` | Inference backend: `mps`, `mlx`, `cpu` |\n| `--quantize` | `none` | Quantization: `int8`, `int4`, `none` |\n| `--steps` | `28` | Inference steps (more = higher quality) |\n| `--seed` | `42` | Random seed for reproducibility |\n| `--quality` | - | Preset: `fast`, `balanced`, `high` |\n| `--tile` | `false` | Enable tiling for large images |\n| `--tile-size` | `512` | Tile size in pixels |\n| `--tile-overlap` | `64` | Tile overlap in pixels |\n| `--json` | `false` | Force JSON output in terminal |\n\n## Contributing\n\nContributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and guidelines.\n\nAreas where help is especially useful:\n- CUDA/ROCm backend support\n- MLX performance improvements\n- New restoration tasks\n- Benchmarks on different Apple Silicon chips\n\n## License\n\n[MIT](LICENSE)\n\n---\n\u003cdiv align=\"center\"\u003e\n\nBuilt by [Boris Djordjevic](https://github.com/longevityboris) at [199 Biotechnologies](https://github.com/199-biotechnologies) | [Paperfoot AI](https://paperfoot.ai)\n\n\u003cbr /\u003e\n\n**If this is useful to you:**\n\n[![Star this repo](https://img.shields.io/github/stars/paperfoot/realrestore-cli?style=for-the-badge\u0026logo=github\u0026label=%E2%AD%90%20Star%20this%20repo\u0026color=yellow)](https://github.com/paperfoot/realrestore-cli/stargazers)\n\u0026nbsp;\u0026nbsp;\n[![Follow @longevityboris](https://img.shields.io/badge/Follow_%40longevityboris-000000?style=for-the-badge\u0026logo=x\u0026logoColor=white)](https://x.com/longevityboris)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaperfoot%2Frealrestore-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaperfoot%2Frealrestore-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaperfoot%2Frealrestore-cli/lists"}