Back to Czkawka

Czkawka CLI - Instructions

instructions/Instruction_CLI.md

12.0.022.3 KB
Original Source

Czkawka CLI - Instructions

Czkawka CLI is a terminal frontend for czkawka_core that exposes all scanning tools as subcommands, suitable for scripting and automation.

Table of Contents


Glossary

For shared concepts (reference paths, cache, prehash, hard links) see Terminology in the main guide. CLI-specific terms below.

TermDefinition
Included directory (-d)Directory to scan. Required for all tools. Multiple values can be listed.
Excluded directory (-e)Directory skipped entirely during scanning. Faster than excluded items for folder-level exclusions.
Excluded items (-E)Glob patterns matched against full paths (e.g. */tmp*, */.git). More flexible than -e but slightly slower.
Reference directory (-r)A directory whose files appear in results for comparison only. Files inside are never deleted or modified by --delete-method. Available for: dup, image, video, music.
Delete method (-D)Selects which file in each group is kept and which are removed. Codes: AEN, AEO, AEB, AES, ON, OO, OB, OS, HARD, NONE. See the dup section for details.
Dry run (-Q)Shows what operations would be performed without executing them. Always use before a real deletion run.
Extension macrosShorthand groups for -x/-P: IMAGE (jpg,kra,gif,png,bmp,tiff,...), VIDEO (mp4,flv,mkv,webm,...), MUSIC (mp3,flac,ogg,...), TEXT (txt,doc,docx,...).

Requirements

Prebuilt binaries work on Linux (Ubuntu 22.04+), Windows 10+, and macOS 10.15+.

Optional runtime dependencies:

  • ffmpeg - required for video (similar videos) and video-optimizer
  • libheif / libraw / libavif - only if compiled from source with those features

Install ffmpeg:

OSCommand
Linuxsudo apt install ffmpeg
macOSbrew install ffmpeg
Windowschoco install ffmpeg or download from ffmpeg.org and place ffmpeg.exe in PATH

Compile from source:

shell
cargo build --release --bin czkawka_cli
# With optional image format support:
cargo build --release --bin czkawka_cli --features "heif,libraw,libavif"

Quick Start

shell
# List all tools
czkawka_cli --help

# Show options for a specific tool
czkawka_cli dup --help

# Find duplicate files in a directory (results printed to console)
czkawka_cli dup -d /home/user/Documents

# Save results to file without printing
czkawka_cli dup -d /home/user/Documents -f results.txt -N

# Dry run - preview which files would be deleted (keeps newest in each group)
czkawka_cli dup -d /home/user/Documents -D AEN -Q

# Delete duplicates keeping newest, move others to trash
czkawka_cli dup -d /home/user/Documents -D AEN -y

Common Flags

These flags are available for every tool:

FlagLongDefaultDescription
-d--directories(required)One or more directories to scan
-e--excluded-directories-Directories to skip entirely
-E--excluded-items-Glob patterns to exclude (e.g. */tmp*)
-x--allowed-extensions(all)Only scan these extensions. Macros: IMAGE, VIDEO, MUSIC, TEXT
-P--excluded-extensions-Skip files with these extensions
-f--file-to-save-Save results to a human-readable text file
-C--compact-file-to-save-Save results as compact (minified) JSON
-p--pretty-file-to-save-Save results as pretty-printed JSON
-R--not-recursivefalseScan top-level directory only (no recursion)
-X--exclude-other-filesystemsfalseSkip files on other filesystems (Linux/macOS)
-T--thread-number0 (all)Limit CPU threads; 0 = all available
-N--do-not-print-resultsfalseSuppress result output to console
-M--do-not-print-messagesfalseSuppress all messages, warnings, errors
-W--ignore-error-code-on-foundfalseReturn exit code 0 even when files found
-H--disable-cachefalseDisable the hash/metadata cache entirely

Grouped delete flags

Used by tools that produce groups (dup, image, video, music):

FlagLongDefaultDescription
-D--delete-methodNONEDeletion strategy (see codes below)
-Q--dry-runfalsePreview operations without executing
-y--move-to-trashfalseMove to system trash instead of permanent delete

Delete method codes:

CodeKeepsDeletes
AENNewest fileAll others
AEOOldest fileAll others
AEBBiggest fileAll others
AESSmallest fileAll others
ONNewest onlyEverything else
OOOldest onlyEverything else
OBBiggest onlyEverything else
OSSmallest onlyEverything else
HARD(all, linked)Replaces duplicates with hard links
NONE(all)Nothing - results only, default

Simple delete flags

Used by tools that produce flat lists (empty-folders, empty-files, temp, symlinks, broken):

FlagLongDefaultDescription
-D--delete-filesfalseDelete all found items
-Q--dry-runfalsePreview only
-y--move-to-trashfalseMove to trash instead

Output Formats and Exit Codes

All three output formats can be combined in a single command:

  • Text (-f results.txt) - human-readable, one entry per line with group headers
  • Compact JSON (-C results.json) - minified JSON, parse with jq or scripts
  • Pretty JSON (-p results_pretty.json) - indented JSON, same structure as compact

Exit codes:

CodeMeaning
0Success, no matching files found (or -W flag set)
1An error occurred
11Success, matching files were found

Use -W / --ignore-error-code-on-found in CI/scripts where "files found" is not an error condition.


Tools

dup - Duplicate Files

shell
czkawka_cli dup -d <dirs> [options]
FlagDefaultDescription
-s / --search-methodHASHNAME, SIZE, SIZE_NAME, HASH
-t / --hash-typeBLAKE3BLAKE3, XXH3, CRC32
-m / --minimal-file-size8192Minimum file size in bytes
-i / --maximal-file-size(max u64)Maximum file size in bytes
-u / --use-prehash-cachefalseCache partial hashes for faster re-scans
-Z / --minimal-prehash-cache-file-size257144Min size to store in prehash cache
-c / --minimal-cached-file-size257144Min size to store in hash cache
-l / --case-sensitive-name-comparisonfalseCase-sensitive name comparison (NAME method)
-L / --allow-hard-linksfalseTreat hard links as separate files
-r / --reference-directories-Reference dirs (scanned but never deleted)
-D / -Q / -yNONE/false/falseDelete method / dry-run / move-to-trash

Hash method recommendations:

  • Use HASH (default) for reliable deduplication.
  • Use NAME only as a quick experiment - many false positives.
  • Use SIZE / SIZE_NAME only for a rough pre-screen.

Examples:

shell
# Find duplicates >= 25 bytes in /home/rafal, skip Obrazy dir, IMAGE extensions only
czkawka_cli dup -d /home/rafal -e /home/rafal/Obrazy -m 25 -x IMAGE -f results.txt

# Dry run: show which files would be deleted keeping newest
czkawka_cli dup -d /home/data -D AEN -Q

# Protect /backup, remove duplicates from /incoming, move to trash
czkawka_cli dup -d /incoming -r /backup -D AEN -y

empty-folders

shell
czkawka_cli empty-folders -d <dirs> [options]

Finds directories with no files or subdirectories.

FlagDefaultDescription
-D / -Q / -yfalse/false/falseDelete / dry-run / move-to-trash

Example:

shell
czkawka_cli empty-folders -d /home/rafal/rr /home/gateway -f results.txt

big - Big Files

shell
czkawka_cli big -d <dirs> [options]
FlagDefaultDescription
-n / --number-of-files50Number of files to show
-J / --smallest-modefalseFind smallest files instead of biggest
-D / -Q / -yDelete / dry-run / trash

Example:

shell
czkawka_cli big -d /home/rafal/ /home/piszczal -e /home/rafal/Roman -n 25 -x VIDEO -f results.txt

empty-files

shell
czkawka_cli empty-files -d <dirs> [options]
FlagDefaultDescription
--zero-byte-contentfalseAlso find files whose entire content is null bytes (\0)
--non-printable-contentfalseAlso find files with only non-printable ASCII characters (implies --zero-byte-content)
-D / -Q / -yDelete / dry-run / trash

Example:

shell
czkawka_cli empty-files -d /home/rafal /home/szczekacz -e /home/rafal/Pulpit -R -f results.txt

temp - Temporary Files

shell
czkawka_cli temp -d <dirs> [options]
FlagDefaultDescription
-L / --extensions(built-in list)Override the list of temporary patterns. If specified, replaces the defaults entirely. Matched using ends_with on the lowercased filename.
-D / -Q / -yDelete / dry-run / trash

Default patterns: #, thumbs.db, .bak, ~, .tmp, .temp, .ds_store, .crdownload, .part, .cache, .dmp, .download, .partial

Example:

shell
czkawka_cli temp -d /home/rafal/ -E */.git */tmp* *Pulpit -f results.txt -D

image - Similar Images

shell
czkawka_cli image -d <dirs> [options]
FlagDefaultDescription
-s / --max-difference5Max hash distance (0-40). Lower = stricter.
-g / --hash-algGradientMean, Gradient, Blockhash, VertGradient, DoubleGradient, Median
-c / --hash-size16Hash resolution: 8, 16, 32, 64
-z / --image-filterNearestLanczos3, Nearest, Triangle, Gaussian, CatmullRom
--geometric-invarianceoffoff, mirror-flip, mirror-flip-rotate90
-m / --minimal-file-size16384Min size in bytes
-i / --maximal-file-size(max)Max size in bytes
-J / --ignore-same-sizefalseSkip images with identical byte size
-Z / --ignore-same-resolutionfalseSkip images with identical pixel dimensions
-L / --allow-hard-linksfalseTreat hard links as separate files
-r / --reference-directories-Reference directories
-D / -Q / -yDelete method / dry-run / trash

Choosing parameters:

  • Start with --max-difference 5, --hash-size 16, --hash-alg Gradient and adjust from there.
  • For high-similarity matching (e.g., thumbnails vs originals), lower --max-difference (0-3).
  • For matching across compression/watermarks, raise it (10-20 for hash-size 16).
  • --geometric-invariance mirror-flip-rotate90 catches mirrored or rotated copies but is slower.

Example:

shell
czkawka_cli image -d /home/rafal/ -E */.git */tmp* *Pulpit -f results.txt

video - Similar Videos

Requires ffmpeg installed.

shell
czkawka_cli video -d <dirs> [options]
FlagDefaultDescription
-t / --tolerance10Frame difference threshold (0-20)
-A / --scan-duration10Seconds of video to scan per file
-U / --skip-forward-amount15Seconds to skip at the start of each video
-B / --crop-detecttrueDetect and ignore letterbox black bars before hashing
--window-count(default)Temporal windows per video (1-20; more = more accurate, slower)
--duration-tolerance-pct(default)Max % duration difference for two videos to be compared
--min-matching-windows(default)Min fraction of matching windows to call videos similar
--subclip-min-match(default)Fraction for subclip detection (a clip inside a longer video)
--check-audio-contentfalseAlso compare audio fingerprints (very slow, opt-in)
--generate-thumbnailsfalsePre-populate thumbnail cache for GUI
-J / --ignore-same-sizefalseIgnore groups with same file size
-Z / --ignore-same-resolutionfalseIgnore groups with same video resolution
-r / --reference-directories-Reference directories
-D / -Q / -yDelete method / dry-run / trash

Example:

shell
czkawka_cli video -d /home/rafal -f results.txt

music - Same Music

shell
czkawka_cli music -d <dirs> [options]
FlagDefaultDescription
-s / --search-methodTAGSTAGS or CONTENT
-z / --music-similaritytrack_title,track_artistComma-separated tag fields to compare
-a / --approximate-comparisonfalseAllow small differences in tag values
-c / --compare-fingerprints-only-with-similar-titlesfalseSpeed up CONTENT mode by pre-filtering on title similarity
-l / --minimum-segment-duration10.0Minimum audio segment length in seconds to compare
-Y / --maximum-difference2.0Max allowed audio segment difference (0.0-10.0)
-m / --minimal-file-size8192Min file size in bytes
-r / --reference-directories-Reference directories
-D / -Q / -yDelete method / dry-run / trash

Available tag fields for -z: track_title, track_artist, year, bitrate, genre, length

Example:

shell
czkawka_cli music -d /home/rafal -e /home/rafal/Pulpit -z "track_artist,year" -f results.txt

shell
czkawka_cli symlinks -d <dirs> [options]

Finds symbolic links that point to non-existent targets or form circular chains (>20 jumps).

FlagDefaultDescription
-D / -Q / -yfalse/false/falseDelete / dry-run / trash

Example:

shell
czkawka_cli symlinks -d /home/kicikici/ /home/szczek -e /home/kicikici/jestempsem -x jpg -f results.txt

broken - Broken Files

shell
czkawka_cli broken -d <dirs> [options]

Finds files that fail to open correctly with their expected library.

FlagDefaultDescription
-c / --checked-typesPDF,AUDIO,IMAGE,ARCHIVE,FONT,MARKUPTypes to check (comma-separated list)
-D / -Q / -yDelete / dry-run / trash

Available type values:

ValueChecks
IMAGEjpg, jpeg, png, tiff, gif, bmp, ico, webp, exr, avif, others
AUDIOmp3, flac, wav, ogg, m4a, aac, others
PDFpdf
ARCHIVEzip, 7z, gz/tgz, tar, zst, bz2, xz
FONTttf, otf, ttc
MARKUPJSON, XML, TOML, YAML, SVG
VIDEO_FFPROBEFast header-only video check (requires ffmpeg)
VIDEO_FFMPEGFull decode check - slow, most thorough (requires ffmpeg)

False positives are possible. Verify files manually before deletion.

Example:

shell
czkawka_cli broken -d /home/kicikici/ -x jpg -f results.txt

ext - Bad Extensions

shell
czkawka_cli ext -d <dirs> [options]

Finds files whose content (detected from magic bytes) does not match their current extension.

FlagDefaultDescription
-F / --fix-extensionsfalseRename files to the correct extension automatically

Example:

shell
czkawka_cli ext -d /home/czokolada/ -f results.txt

bad-names

shell
czkawka_cli bad-names -d <dirs> [options]

At least one check flag must be enabled, otherwise no files will match.

FlagDefaultDescription
-u / --uppercase-extensionfalseDetect uppercase extensions (e.g. .JPG)
-j / --emoji-usedfalseDetect emoji characters in filenames
-w / --space-at-start-or-endfalseDetect leading or trailing spaces
-n / --non-ascii-graphicalfalseDetect non-ASCII graphical characters
-r / --restricted-charset-Allowed special characters; others are flagged (e.g. _- .)
-a / --remove-duplicated-non-alphanumericfalseDetect doubled non-alphanumeric chars (e.g. file__name)
-F / --fix-namesfalseRename files automatically to suggested fixed name
-D / -Q / -yDelete / dry-run / trash

Example:

shell
czkawka_cli bad-names -d /home/rafal -u -j -w -n -f results.txt

exif-remover

shell
czkawka_cli exif-remover -d <dirs> [options]

Finds image files containing EXIF metadata. Optionally removes tags.

Supported formats: jpg, jpeg, jfif, png, tiff, tif, avif, jxl, webp, heic, heif.

FlagDefaultDescription
-i / --ignored-tags-Comma-separated tag names to keep (e.g. Orientation,DateTime)
-F / --fix-exiffalseActually remove EXIF tags
-o / --override-filefalseOverwrite originals (default: write _cleaned copy)

Example:

shell
czkawka_cli exif-remover -d /home/rafal -x IMAGE -F -f results.txt

video-optimizer

shell
czkawka_cli video-optimizer -d <dirs> transcode [options]
czkawka_cli video-optimizer -d <dirs> crop [options]

Requires ffmpeg at runtime when using -F to actually process videos.

transcode

Identifies videos using inefficient codecs.

FlagDefaultDescription
-c / --excluded-codecs-Codecs to skip/exclude (e.g. h265,av1,vp9)
--target-codech265Target codec when -F is set: h264, h265, av1, vp9
--quality23Encoding quality (0-51; lower = better quality, larger file)
--noise-reductionnonenone or hqdn3d (general-purpose denoiser)
--noise-reduction-strength5Denoiser strength (1-10)
--custom-ffmpeg-command-Custom ffmpeg arguments; overrides most encoding options
-t / --generate-thumbnailsfalseGenerate thumbnail cache
-V / --thumbnail-percentage10Frame position % for thumbnail (1-99)
-F / --fix-videosfalseActually transcode found videos
--overwrite-originalfalseReplace original files
--fail-if-not-smallerfalseSkip files where output is not smaller than original
--limit-video-sizefalseCap video dimensions
--max-width1920Max width in pixels (only with --limit-video-size)
--max-height1080Max height in pixels (only with --limit-video-size)

crop

Identifies videos with black bars (letterbox/pillarbox) or static edge content.

FlagDefaultDescription
-m / --crop-mechanismblackbarsblackbars or staticcontent
-k / --black-pixel-threshold32Pixel value threshold for "black" (0-128; lower = stricter)
-b / --black-bar-percentage90Min % of black pixels in a row/column to call it a bar
-s / --max-samples20Max frames to sample (5-1000)
-z / --min-crop-size10Minimum crop region size in pixels
-t / --generate-thumbnailsfalseGenerate thumbnail cache
-F / --fix-videosfalseActually crop the found videos
--overwrite-originalfalseReplace original files
--target-codec-Optionally also transcode during crop

Examples:

shell
# Find videos not already in h265 or av1
czkawka_cli video-optimizer -d /home/rafal transcode -c h265,av1 -f results.txt

# Dry run: preview what would be transcoded to h265
czkawka_cli video-optimizer -d /home/rafal transcode -F -Q

# Find videos with black bars
czkawka_cli video-optimizer -d /home/rafal crop -m blackbars -f results.txt

Automation Examples

Nightly duplicate report saved as JSON (cron)

shell
#!/bin/bash
czkawka_cli dup \
    -d /home/user/Documents /home/user/Downloads \
    -e /home/user/.cache \
    -p /home/user/logs/duplicates_$(date +%Y%m%d).json \
    -N -M -W

CI: fail if any empty files exist in build output

shell
czkawka_cli empty-files -d ./build_output -N -M
# exit code 11 if empty files found, 0 if none

Interactive cleanup with dry-run confirmation

shell
#!/bin/bash
dir="${1:?Usage: $0 <directory>}"

echo "=== Dry run: temporary files in $dir ==="
czkawka_cli temp -d "$dir" -Q -D

echo ""
read -p "Proceed with deletion? [y/N] " answer
if [[ "$answer" == "y" ]]; then
    czkawka_cli temp -d "$dir" -D
    echo "Done."
fi

Protect originals, clean up incoming duplicates

shell
# /archive is reference - never deleted
# /incoming is cleaned - duplicates moved to trash
czkawka_cli dup \
    -d /incoming \
    -r /archive \
    -D AEN \
    -y

Pre-populate video thumbnail cache for Krokiet

shell
# Run CLI scan so Krokiet gets instant thumbnails next time it opens
czkawka_cli video -d /your/videos --generate-thumbnails -N -M -W

Find images with GPS data and strip it

shell
# Dry run first - see what has EXIF
czkawka_cli exif-remover -d /home/user/Photos -x IMAGE -f exif_report.txt

# Strip all EXIF tags (keep Orientation), override original files
czkawka_cli exif-remover -d /home/user/Photos -x IMAGE -F -o -i "Orientation"