Image watermarker CLI tool written in Golang
  • Go 53.9%
  • TypeScript 20.8%
  • JavaScript 9.5%
  • CSS 8.2%
  • HTML 7.1%
  • Other 0.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-08-16 11:49:43 +02:00
frontend Added aspect ratio preservation logic 2026-08-16 11:49:43 +02:00
.gitignore Javascript to Typescript migration 2026-07-25 18:40:32 +02:00
app.go Added output format selection 2026-07-30 21:29:17 +02:00
bugstofix.txt Added bug to fix 2026-05-25 14:38:59 +02:00
build.sh Added lighter executable build flags for cli exec 2026-07-30 21:37:23 +02:00
config.go go fix 2026-07-30 11:02:56 +02:00
config_test.go Added tests for config.go 2026-07-30 17:06:33 +02:00
global.go Added output format selection 2026-07-30 21:29:17 +02:00
go.mod Moved from default flag to spf/pflag & upgrade to 1.26.4 2026-07-05 15:31:59 +02:00
imageprocessor.go Added output format selection 2026-07-30 21:29:17 +02:00
imageprocessor_test.go Added output format selection 2026-07-30 21:29:17 +02:00
LICENSE Removed unnecessary files and added license 2026-07-22 14:46:41 +02:00
main_cli.go Added output format selection 2026-07-30 21:29:17 +02:00
main_gui.go Cleared TODO 2026-07-29 12:54:04 +02:00
README.md Merge branch 'main' of https://codeberg.org/cieldeb/watermarker 2026-07-27 21:33:08 +02:00
wails.json Javascript to Typescript migration 2026-07-25 18:40:32 +02:00
watermark.go First implementation of wm dimensions instead of size ratio 2026-07-30 09:52:03 +02:00
watermark_test.go First implementation of wm dimensions instead of size ratio 2026-07-30 09:52:03 +02:00

Watermarker

A fast Go tool for batch-watermarking images, available as a CLI and as a desktop GUI (via Wails).

Point it at a folder or a file, give it a watermark image, and it stamps every JPEG/PNG it finds with a resized, positioned, opacity-adjusted copy of that watermark — writing output atomically so a crash mid-run never leaves a corrupt file behind.

Features

  • Batch-processes a single image, a directory, or several paths at once
  • Optional recursive processing of subdirectories
  • Watermark size, opacity, position (anchor + pixel offsets) are all configurable
  • Per-run JPEG quality control, with automatic lossless PNG output at quality 100
  • Persistent YAML config so you don't have to repeat flags every run (addition of other file formats plausible in the future but not a priority at the moment)
  • Safe by default: won't overwrite existing files unless --overwrite is passed
  • Multiple configurations can be saved side by side
  • Optional GUI built with Wails, sharing the same core image-processing code as the CLI

Building

Requires Go 1.26+.

./build.sh

This formats the code, builds the CLI (watermarker-cli), and installs it to ~/.local/bin/. If the Wails CLI is installed, it also builds the GUI (watermarker-gui) and installs it alongside. It's a thin convenience wrapper, not a build spec — see below for what it's actually doing and how to do it yourself.

Building the CLI manually

main_cli.go carries the //go:build !gui constraint and main_gui.go/app.go carry //go:build gui, so a plain build with no tags compiles only the CLI entry point:

go build -o watermarker-cli .

Cross-compiling works the normal Go way, e.g. for a Linux ARM64 target from any host:

GOOS=linux GOARCH=arm64 go build -o watermarker-cli .

Building the GUI manually

The GUI needs the gui build tag (to pull in main_gui.go/app.go instead of main_cli.go) plus a webkit tag that must match the WebKitGTK dev package installed on the build machine:

  • webkit2_41 — WebKitGTK 4.1, present on newer distros (Debian 13, Ubuntu 24.04+, current Arch/Fedora). This is what build.sh uses.
  • omit it entirely — WebKitGTK 4.0, for older distros that don't ship the 4.1 dev package.

A raw go build with the gui tag will compile and type-check the Go side, but it won't regenerate JS/TS bindings or bundle the frontend — it's only useful as a quick compile check:

go build -tags "gui webkit2_41" .

For an actual runnable GUI binary, use the Wails CLI, which additionally runs wails generate module and the frontend's npm run build before compiling Go:

wails build -tags "gui webkit2_41"

Drop webkit2_41 from that command on older distros. For live-reload development instead of a production build:

wails dev -tags "gui webkit2_41"

Usage

watermarker-cli [flags] [path...]

If no path is given, the current working directory is used. Each path can be a single image or a directory (directories are scanned for .png/.jpg/.jpeg files).

Examples

Watermark every image in the current directory, writing output next to the originals with a _wm suffix:

watermarker-cli --wmpath="logo.png"

Watermark a whole photo library recursively, sending output to a separate folder:

watermarker-cli --wmpath="logo.png" --recursive --outputdir="/tmp/watermarked"

Overwrite images in place (prompts for confirmation unless -y is passed):

watermarker-cli --wmpath="logo.png" --overwrite -y

Save the current flags as your default configuration:

watermarker-cli --wmpath="logo.png" --wmsizeratio=15 --wmanchor=bottomRight --saveconfig

Flags

Flag Description Default
-c, --configuration Configuration to be used on this run —
-o, --outputdir Output folder for the processed images /tmp
--openoutput Open output folder upon completion true
--outputsuffix Suffix appended to output filenames _wm
-r, --recursive Also process subdirectories false
--overwrite Overwrite existing files in the output location false
--hidden Also process hidden files/directories (dotfiles) false
--quality JPEG quality (1–100); 100 forces lossless PNG output 92
--wmpath Path to the watermark image —
--wmsizeratio Watermark size as a percentage of the target image's largest dimension 12
--wmopacity Watermark opacity, 0 (invisible) to 1 (full) 1
--wmxoffset Watermark horizontal offset (% of image width) 4
--wmyoffset Watermark vertical offset (% of image width) 4
--wmanchor Anchor position: combine top/bottom/middle with Left/Right/Center, e.g. bottomRight bottomRight
-y Skip confirmation prompts false
--verbose Verbose (debug) logging false
--saveconfig Save the current flag values to the config file false
--displayconfig Print the current configuration and exit false

Run watermarker-cli --help for the full, up-to-date list.

Configuration file

Settings persist in a YAML file at $XDG_CONFIG_HOME/watermarker/default.yaml (or ~/.config/watermarker/default.yaml if XDG_CONFIG_HOME is unset). It's created automatically on first run with sane defaults, and updated whenever --saveconfig is passed. Command-line flags always take precedence over the config file for the current run.

GUI

The GUI shares the config and watermarking logic with the CLI, built as a desktop app with Wails. Install the Wails CLI first, then see Building the GUI manually above for the exact build/dev commands and build tags.

The frontend source lives in frontend/.

Project layout

  • main_cli.go — CLI entry point and flag definitions (build tag: not gui)
  • main_gui.go, app.go — Wails GUI entry point and bound app methods (build tag: gui)
  • watermark.go — watermark resizing, opacity, and positioning logic
  • imageprocessor.go — image I/O, directory walking, and atomic file writes
  • config.go — YAML config loading/saving via Viper
  • global.go — shared flags, globals, and loggers
  • frontend/ — GUI frontend source

License

Licensed under the GNU General Public License v3.0 or later. See LICENSE for the full text.