DuoBolt CLI

Overview

DuoBolt CLI is the command-line companion to the DuoBolt desktop app. It is designed for power users, automation workflows, CI pipelines, and server environments where a graphical interface is unnecessary.

CLI Only

This page is only about the CLI. If you want the graphical app, read the Desktop Guide instead.

The CLI performs the exact same duplicate file detection as the desktop app — including BLAKE3 hashing with default head+tail prehash (toggle with --no-prehash), symlink handling, and extension-based filtering.

Built with Rust

The CLI is implemented in Rust for maximum performance and reliability.

---

Installation

macOS / Linux

Desktop (macOS) via Homebrew: brew tap rnine/duobolt then brew install --cask duobolt-desktop.

1. Install with Homebrew (recommended):

   Homebrew

   brew tap rnine/duobolt
   brew install duobolt

2. Verify it works:

   Test CLI

   duobolt-cli --version

3. Or download the CLI binary (duobolt-cli) from the Download CLI section and move it into your PATH:

   Manual install

   sudo mv duobolt-cli /usr/local/bin/

Windows

1. Install with Scoop (recommended):

   Scoop

   scoop bucket add duobolt https://github.com/rnine/scoop-duobolt
   scoop install duobolt

2. Verify it works:

   Test CLI

   duobolt-cli --version

3. Or download the .exe binary and place it anywhere in your PATH, for example:

   Example location

   C:\Tools\duobolt-cli.exe

---

Basic Usage

Basic syntax

duobolt-cli <directory...> [options]

You can specify one or more directories to scan.

Examples:

Single directory

duobolt-cli ~/Documents

Multiple directories

duobolt-cli ~/Documents ~/Pictures --min-size=1M

---

Main Options

Head+tail prehashing is enabled by default and recommended. Use --no-prehash only if you explicitly need full hashing on every file.

Option	Description
--min-size=SIZE	Minimum file size. Accepts raw bytes or K/M/G/T/P/E + KiB…EiB.
--chunk=MiB|auto	Hashing chunk size tuning (default: auto).
--no-prehash	Disable head+tail prehash (enabled by default).
--threads=N	Hashing (worker) threads (default: #CPUs).
--follow-symlinks	Follow directory symlinks.
--no-symlink-collapse	Treat hardlinks/symlinks as unique.
--ignore-system-files	Skip system files (.DSStore, Thumbs.db, desktop.ini, .*).
--ignore-library-containers	Skip macOS ~/Library/{Containers,Group Containers} (macOS only).
--ignore-hidden-files	Skip files whose name starts with ’.’ (hidden files).
--ignore-hidden-dirs	Skip directories whose name starts with ’.’.
--only-ext=.mp3,.wav	Include only these file extensions (comma-separated, with dot).
--exclude-ext=.csv,.js	Exclude these file extensions.
--exclude-dir-ext=.app,.bundle	Exclude directories with these extensions.
--output=txt|json|csv	Output format (default: txt).
--quiet	Suppress the progress line.

---

Cache Options

Option	Description
--no-cache	Disable hash cache.
--cache-min-size-local=SIZE	Cache minimum file size for local volumes.
--cache-min-size-network=SIZE	Cache minimum file size for network volumes.
--cache-max-entries=N	Cache entry limit (0 = unlimited).
--cache-max-bytes=SIZE	Cache size limit (0 = unlimited).
--cache-preload-max-entries=N	Preload entry limit (0 = unlimited).
--cache-preload-max-bytes=SIZE	Preload size limit (0 = unlimited).
--cache-stats	Show cache statistics and exit.
--cache-clear	Clear cache and exit.

When --quiet is not set, the CLI prints cache metrics and stats at the end of the run.

Examples

Basic

Simple scan:

Scan a directory

duobolt-cli ~/Photos

Export results as JSON:

JSON output

duobolt-cli ~/Music --output=json --quiet > dupes.json

Filtering

Only scan audio files:

Filter by extension

duobolt-cli ~/Audio --only-ext=wav,flac

Ignore OS junk + disable prehash (full hashing only):

Ignore system files

duobolt-cli ~/Projects --ignore-system-files --no-prehash

Performance

Full-speed multi-threaded scan:

Custom thread count

duobolt-cli D:\Data --threads=12

Disable cache for a one-off scan:

No cache

duobolt-cli ~/Backups --no-cache

Scan multiple directories:

Multiple paths with size filter

duobolt-cli ~/Documents ~/Pictures --min-size=1M

---

Exit Codes

Code	Meaning
0	No duplicates found
2	Duplicates detected
130	Cancelled by user (Ctrl-C)
Other	Error occurred

---

Integration & Automation

Cron Jobs

Schedule regular scans on servers and workstations.

CI/CD Pipelines

Detect duplicates in build artifacts and deployments.

Server Deduplication

Clean up file servers and shared storage.

NAS / Media Libraries

Manage large photo/video collections efficiently.

Example automation script (macOS/Linux):

Automated scan script

#!/bin/bash
duobolt-cli /mnt/storage --output=json --quiet > /var/reports/dupes.json

---

Future Roadmap

Coming Soon

• Native structured logging
• JSONLines output for pipelines

---

Next Steps

DuoBolt Desktop Visual workflow if you prefer a UI

Core Concepts Understand the engine and defaults

FAQ Common questions about Desktop vs CLI

Changelog Release notes and version history