scan

fialr scan <target> [options]

Traverse a directory, compute BLAKE3 and SHA256 hashes for every file, detect MIME types, and generate a structured manifest. Read-only. No files are modified.

Arguments

Argument	Description
`target`	Directory to scan (required)

Options

Option	Description
`-o`, `--output PATH`	Write manifest JSON to this path
`-v`, `--verbose`	Show debug logs
`-q`, `--quiet`	Suppress status output

What it does

scan walks the target directory recursively and builds a manifest.json containing:

Relative path, absolute path, file size
BLAKE3 hash (primary, canonical identifier)
SHA256 hash (secondary, cross-tool verification)
MIME type (via python-magic)
Exclusion records with reasons

Every file is hashed in full. There is no sampling or partial-read mode. The buffer size for hashing is configurable in fialr.toml under [inventory].buffer_size (default: 256 KB).

Exclusion system

The scan respects fialr’s four-layer exclusion system:

Hardcoded — .git/, node_modules/, .venv/, __pycache__/, .ssh/, .gnupg/, .Trash/, system directories, and project roots (detected by sentinel files like package.json, Cargo.toml, pyproject.toml)
Config directories — explicit paths in fialr.toml under [exclusions].directories
Config patterns — globs in fialr.toml under [exclusions].patterns
XATTR/sentinel opt-out — com.fialr.exclude extended attribute or .fialr-exclude sentinel file

Every excluded file is recorded in the manifest with its exclusion reason and the layer that triggered it. Nothing is silently skipped.

macOS iCloud handling

On macOS, fialr detects iCloud Drive sync state via the platform adapter. Files that are evicted (cloud-only, not downloaded) are recorded in the manifest but not hashed, since their content is not available on disk. The sync state is noted in the manifest entry.

Output

To stderr (human-readable):

scan ~/Documents

  SCAN  847 files (2.3s)
────────────────────────────────────────────────────────
     files  847
  excluded  23
    errors  0
      time  2.3s

When --output is specified, the manifest JSON is written to the given path. Without --output, the manifest is held in memory only and used as input to subsequent pipeline stages.

Examples

# Scan a directory
fialr scan ~/Documents

# Write manifest to file
fialr scan ~/Documents -o manifest.json

# Quiet mode -- errors only
fialr scan ~/Documents -q