Skip to content
fialr

validate

fialr validate <target> [options]

Check that tracked files exist at recorded paths, have correct BLAKE3 hashes, and carry valid XATTRs. Reports discrepancies as a delta report.

Arguments

Section titled “Arguments”
ArgumentDescription
targetRoot directory to validate (required)

Options

Section titled “Options”
OptionDescription
--check CHECKRun a specific check: paths, hashes, xattrs, or all (default: all)

Check modes

Section titled “Check modes”

The --check flag selects which integrity checks to run.

paths

Section titled “paths”

Verify that every file recorded in the database with a current path actually exists on disk. Reports missing files.

hashes

Section titled “hashes”

Recompute the BLAKE3 hash of every tracked file and compare against the database record. Reports mismatches — files whose content has changed since they were last recorded.

xattrs

Section titled “xattrs”

Verify that extended attributes on each file match the database records. Reports files where XATTR values have drifted from the authoritative SQLite records.

all (default)

Section titled “all (default)”

Run all three checks in sequence. This is the most thorough mode and the default when --check is not specified.

What it does

Section titled “What it does”

validate reads from the SQLite database and compares its records against the current filesystem state. It does not modify files, database records, or XATTRs. It produces a report of discrepancies.

Each discrepancy includes:

  • The check that failed (path_exists, hash_match, xattr_match)
  • The file path
  • The content hash
  • The specific error

Automatic validation at job close

Section titled “Automatic validation at job close”

Validation runs automatically at the end of every job that modifies files (organize, dedup, enrich with --execute). The job report includes the validation results. If any checks fail, the job report flags the failures.

Output

Section titled “Output”
validate ~/Documents


────────────────────────────────────────────────────────
   checked  847
    passed  844
    failed  3

When failures occur, each is listed:

  FAIL  path_exists  ~/Documents/old-contract.pdf
        File does not exist at recorded path
  FAIL  hash_match   ~/Documents/notes.md
        expected a1b2c3..., got d4e5f6...
  FAIL  xattr_match  ~/Documents/report.pdf
        com.fialr.category: db=financial, xattr=legal

Examples

Section titled “Examples”
Terminal window
# Run all integrity checks
fialr validate ~/Documents


# Verify hashes only
fialr validate ~/Documents --check hashes


# Verify paths only
fialr validate ~/Documents --check paths

See also

Section titled “See also”