Skip to content

CLI Reference

Andrew Paolucci edited this page Nov 19, 2026 · 1 revision

CLI Reference (robocopy2rust)

robocopy2rust.exe (Windows) / robocopy2rust (Linux/macOS) is the unified command-line entry point (crates/robocopy2rust-cli/src/main.rs). Invoking it with no subcommand automatically launches the platform default GUI (robocopy2rust-win32.exe on Windows, robocopy2rust-iced on Linux/macOS).


Global Options & Signal Handling

Flag Default Description
-l, --log-level <LEVEL> warn tracing verbosity (error, warn, info, debug, trace) written to stderr
--log-file <PATH> None Optional log file destination (keeps stdout clean for --json output)
-h, --help — Print CLI help
-V, --version — Print version (0.1.0)

Two-Stage Ctrl+C Cancellation (install_signal_handler)

During dry-run or run:

  1. First Ctrl+C: Cancels the active robocopy.exe child tree cleanly via CancelToken (taskkill /PID ... /T /F on Windows; kill -TERM on Unix) so summary status and exit decoding still complete gracefully.
  2. Second Ctrl+C: Immediately terminates the CLI with exit code 130.

Shared Job Source Arguments (JobSourceArgs)

Used across build, dry-run, run, and profile save:

  • -s, --source <DIR> — Source directory path
  • -d, --dest <DIR> — Destination directory path
  • --preset <ID_OR_NAME> — Base job off one of the 8 built-in presets
  • --profile <NAME> — Load base job from persistent ProfileStore
  • --rcj <PATH> — Load base job from a UTF-8 or UTF-16LE/BE .rcj file
  • --files <SPECS...> — File specifications (e.g. --files *.rs *.toml)
  • --mirror — Enable /MIR /E /PURGE
  • --dry-run — Enable /L list-only dry-run mode
  • --threads <N> — Set /MT:N (1..=128)
  • --retries <N> — Set /R:N
  • --wait <SECS> — Set /W:SECS

Precedence if multiple sources are passed: --rcj > --profile > --preset > RobocopyJob::default(), followed by explicit flag overrides (--source, --dest, --files, --mirror, --dry-run, --threads, --retries, --wait).


Subcommands (11 Commands)

1. presets — List Built-In Job Presets

robocopy2rust presets
robocopy2rust presets --json

2. build — Build Command & Export Scripts

Assembles a validated command and optionally writes .rcj, .bat, .ps1, and a schtasks /Create registration command.

robocopy2rust build `
  --source "C:\Data Src\" `
  --dest "D:\Backup" `
  --preset safe-backup `
  --threads 16 `
  --export-rcj backup.rcj `
  --export-bat backup.bat `
  --export-ps1 backup.ps1 `
  --export-schtasks `
  --task-name "NightlyBackup" `
  --json

Options: --export-rcj <PATH>, --export-bat <PATH>, --export-ps1 <PATH>, --export-schtasks, --task-name <NAME> (default "Robocopy2Rust_Job"), --json.

3. parse — Import Raw CLI or .rcj to Structured JSON

Parses an arbitrary robocopy ... command string or .rcj file into normalized command text, warnings, validation findings, and full RobocopyJob JSON.

robocopy2rust parse 'robocopy "C:\Data Src" "D:\Backup" *.docx /MIR /MT:16 /R:3 /W:5 /XD .git /XF *.tmp' --json
robocopy2rust parse .\legacy.rcj --rcj --json

4. decode — Decode Bitmask Exit Codes (0..=16)

robocopy2rust decode 3
robocopy2rust decode 8 --json

5. dry-run — Safe /L Preview Simulation

Forces /L /FP /BYTES (with_list_only), streams output, appends to history.json, and optionally writes an offline report.

robocopy2rust dry-run --source "C:\Src" --dest "D:\Dst" --report preview.html
robocopy2rust dry-run --preset exact-mirror --source "C:\Src" --dest "D:\Dst" --report .\audit --report-format all --json

Options: --report <PATH>, --report-format <html|json|markdown|all> (default html), --json, --raw-exit-code.

6. run — Live Execution (With Destructive Safety Guard)

Executes live Robocopy with streaming telemetry and history logging. Refuses /MIR, /PURGE, /MOVE, or /MOV unless -y / --yes is passed.

# Safe incremental run
robocopy2rust run --source "C:\Src" --dest "D:\Dst" --preset safe-backup --report run.html

# Destructive mirror run (requires explicit --yes)
robocopy2rust run --source "C:\Src" --dest "D:\Dst" --mirror --yes --report mirror_audit.html

7. profile — Manage Saved Profiles (profiles.json)

Nested subcommands for CRUD + .rcj conversion on dirs::config_dir()/robocopy2rust/profiles.json:

robocopy2rust profile list [--json]
robocopy2rust profile show "Nightly Docs" [--json]
robocopy2rust profile save "Nightly Docs" --description "Work docs" --source "C:\Docs" --dest "E:\Docs" --preset safe-backup
robocopy2rust profile import-rcj "Legacy Job" .\old_job.rcj --description "Migrated job"
robocopy2rust profile export-rcj "Nightly Docs" .\nightly.rcj
robocopy2rust profile delete "Nightly Docs"

8. report — Convert Existing Log Files Offline

Parses UTF-8, UTF-8 BOM, or UTF-16LE/BE (/UNILOG) Robocopy log files into HTML, JSON, Markdown, or all three (all).

robocopy2rust report --log-file nightly.log --output .\audit_bundle --format all

9. env — Inspect Host Environment

Reports host OS, whether robocopy.exe was detected (including resolved path), and configuration directory.

robocopy2rust env
robocopy2rust env --json

10. mcp — Start stdio MCP Server

Starts the JSON-RPC 2.0 stdio Model Context Protocol server (robocopy2rust_mcp::run_stdio_server()). Also available standalone as robocopy2rust-mcp.

11. gui — Launch Desktop GUI

robocopy2rust gui                  # Win32/WinSafe on Windows; Iced on Linux/macOS
robocopy2rust gui --iced           # Force Iced cross-platform GUI on Windows
robocopy2rust gui --source "C:\A" --dest "D:\B" --profile "Nightly Docs"

Options: --iced, --source <DIR>, --dest <DIR>, --rcj <FILE>, --profile <NAME>.

Clone this wiki locally