CLI Overview

fialr uses a custom help renderer that bypasses argparse’s default display. Help screens follow gh/cargo/stripe conventions: grouped commands, aligned columns, branded color output using the Bronze/Ash palette.

Run fialr with no arguments to see the main help screen. Run fialr <command> --help for command-specific usage.

Command groups

Commands are organized into six groups.

Workflows

Command	Description
`process`	Full pipeline: scan, classify, enrich, rename. Dry-run default.
`organize`	Move enriched files into schema directories
`cleanup`	Dedup and validate. Dry-run default.

Discover

Command	Description
`scan`	Inventory and classify a directory (read-only)
`search`	Search files by metadata, content, semantic similarity, or file similarity

Enrich

Command	Description
`enrich`	Run enrichment pipeline on files (includes embeddings)
`rename`	Apply naming templates to files

Tools

Command	Description
`hash`	Compute BLAKE3 and SHA256 for files
`export`	Generate sidecar metadata files
`vault`	Encrypted vault management
`validate`	Verify file integrity against database
`undo`	Undo previous file operations
`dedup`	Find and stage duplicate files

Status

Command	Description
`status`	Show database stats and recent jobs
`config`	Show, validate, and modify configuration (includes AI provider setup)

License

Command	Description
`activate`	Activate a license key on this machine
`deactivate`	Release the license from this machine
`license`	Display current license status

Global flags

These flags apply to every command.

Flag	Description
`--config PATH`	Path to `fialr.toml` config file
`--db PATH`	Path to SQLite database
`-v`, `--verbose`	Show debug logs (JSON to stderr)
`-q`, `--quiet`	Suppress status output (errors still shown)
`--no-color`	Disable colored output
`--version`	Print version and exit

Output conventions

All user-facing output goes to stderr via the Output class. Stdout is reserved for machine-readable data: JSON manifests, plan CSVs, hash values.

This separation means you can pipe fialr output to other tools without status messages contaminating the data stream:

fialr hash contract.pdf --json | jq .blake3

When --quiet is set, status and field output is suppressed. Errors and warnings are always shown regardless of quiet mode.

Color

Color detection follows this priority:

FORCE_COLOR environment variable — always enable
NO_COLOR environment variable — always disable (per no-color.org)
TERM=dumb — disable
TTY detection — enable if the stream is a terminal

The --no-color flag is equivalent to setting NO_COLOR=1.

Exit codes

Code	Meaning
`0`	Success
`1`	Error (operation failed)
`2`	Usage error (invalid arguments)
`130`	Interrupted (Ctrl-C)

Error reporting

Every error includes context: the file path, the operation attempted, and the job UUID when applicable. An error message without context is considered a bug.

error: Hash mismatch for ~/Documents/contract.pdf: expected a1b2c3..., got d4e5f6..., job=7f8a9b...

Warnings use the same pattern but do not cause a non-zero exit code.