img 0.4 guide

img combines image-host management, everyday image tools, and Markdown reference maintenance. The desktop app bundles the matching CLI. Both use the same storage configuration and SQLite library.

Library

Connect S3/R2/OSS, GitHub, or WebDAV from Storage, then choose directories to index. Custom HTTP providers retain known upload records without claiming unsupported browsing or deletion capabilities.

Search covers indexed scopes. Indexing can pause and resume; the desktop periodically refreshes scopes while running. Failed scans do not imply deletion. Remote records define the library; caches only speed up previews. Clearing a cache, hiding a record, and deleting a remote file are separate actions.

Selection survives grid/list switches and search changes. Copy, download, check, migration, and deletion freeze their targets when started. For images with multiple addresses, links prefer the current storage filter, then the preferred address. Remote deletion requires reviewing the storage and objects; changed versions and active uploads prevent deletion.

img library index --provider oss --prefix articles/
img library list --provider oss --search cover --limit 100
img library show IMAGE_ID
img library check IMAGE_ID
img library download IMAGE_ID --output-dir ./downloads
img library cache --clear

Convert & compress; Resize & crop

These are two sidebar entries alongside Library and Upload. Open or paste one image. Both tools share its parameters; replacing the image resets cropping, rotation, and flips. The preview stays on the left, grouped parameters on the right, with actual output size and save/copy/upload controls below.

• PNG, JPEG, and static WebP processing. JPEG transparency is filled with white by default; choose another background if needed.
• Target-size mode preserves format and dimensions. JPEG/lossy WebP search encoding quality; PNG stays lossless. Unreachable targets are reported.
• Longest-edge or width/height resizing, aspect ratio, free or fixed-ratio cropping, quarter turns, and horizontal/vertical flips. Small images are not enlarged by default.
• Every result is computed from the original input. Preview and export share the renderer, and originals remain unchanged.
• Upload prepares the current result before asking for storage. No local save is required first, and remote files are not overwritten automatically.

GIF, animated WebP, SVG, and AVIF can be uploaded unchanged. These editors do not flatten animation or provide HEIC conversion, layers, or AI retouching.

img process photo.png --output photo.webp --image-format webp
img process photo.png --recipe recipe.json --output-dir ./output
img tasks list
img tasks show TASK_ID

A minimal recipe.json:

{
  "version": 1,
  "encoding": {
    "format": "webp",
    "compression": { "mode": "quality", "quality": 85 }
  }
}

The full ProcessingPlan is defined in crates/img-records/src/processing.rs. Desktop presets do not load annotation, split, stitch, or standalone watermark operations removed from this interface.

Sync

Choose a dedicated WebDAV directory or S3 prefix in Settings → Sync. Configuration, hosting credentials, indexes, hidden state, preferred addresses, and presets sync. Cached images, local file paths, and running tasks do not. The sync connection’s own credentials remain device-local.

Synced hosting credentials are stored in plaintext in your sync directory. Keep it private; img does not additionally encrypt the data. Local credentials use the OS credential store. Environment references remain references, without exporting process environment values.

Conflicts retain both sides until resolved; device clocks do not force an overwrite. Receiving a deletion event never deletes remote images on the user’s behalf. Desktop background sync stops on exit.

img sync status
img sync run
img sync conflicts

Migration and Markdown repair

Select library images and destination storage, review paths and conflicts, then copy. New images are verified before a URL mapping is created. Sources are preserved by default; retries retain verified successes.

img migrate plan IMAGE_ID --to r2 --prefix articles --output move.json
img migrate apply move.json --report report.json
img migrate show TASK_ID
img references scan ./articles --migration TASK_ID --output references.json
img references show REFERENCE_TASK_ID
img references apply REFERENCE_TASK_ID --yes
img references export REFERENCE_TASK_ID ./repair-report
img references restore REFERENCE_TASK_ID

Scanning covers .md and .markdown inside the selected directory: inline images, reference-style images, and HTML <img src>, excluding code. Before applying, documents and destination images are checked again. Atomic replacement follows successful backup; failed files keep their original references. Restoration also creates a preview and uses references apply --yes, backing up the pre-restore content.

References outside the selected directory remain unknown. A scan cannot prove remote deletion safe. Without an accessible original, remote copy, or hash-matched cache, a lost image cannot be recovered.

Installation and updates

The installation page resolves current stable releases. GitHub Actions builds three-platform desktop packages and standalone CLIs with checksums. Desktop settings include update checks and terminal-command installation.

Community macOS builds are not notarized; Windows builds are not code-signed. Follow the installation page’s first-run guidance. Export a backup before upgrading if needed. CLI restore requires the desktop to be closed; credentials are an explicit backup option.