uffs is the command-line interface for Ultra Fast File Search. It reads
NTFS Master File Tables directly and searches millions of files in
milliseconds.
Search is the default action — just type uffs <pattern>. No
command required; management lives under --<command> (§6).
Real commands, real result counts, real measured latency on a hot daemon. Recorded against the real CLI (see the demo kit).
See also: Getting Started · Search Modes · Filters · Sorting · Output Formats
When the first token is not a --command, uffs performs a search. The
first positional argument is the pattern.
uffs <PATTERN> [OPTIONS]
| Syntax | Mode | Detail |
|---|---|---|
*.ext |
Glob | Wildcards *, ?, […] → Search Modes §2 |
word |
Literal | Substring match on full path → Search Modes §3 |
>regex |
Regex | > prefix activates regex → Search Modes §4 |
c:/path* |
Path-aware | Contains separators → Search Modes §5 |
| Prefix | Effect | Detail |
|---|---|---|
path: |
Match against the full path, not just filename | Search Modes §10 |
dir: |
Only search directories | Same as --dirs-only |
file: |
Only search files | Same as --files-only |
| Flag | Effect | Detail |
|---|---|---|
--begins-with <PREFIX> |
Sugar for PREFIX* |
Search Modes §11 |
--ends-with <SUFFIX> |
Sugar for *SUFFIX |
Same |
--contains <NEEDLE> |
Sugar for *NEEDLE* |
Same |
--not-contains <NEEDLE> |
Exclude names containing NEEDLE | Maps to --exclude |
| Flag | Effect | Detail |
|---|---|---|
--case |
Case-sensitive matching | Search Modes §6 |
--smart-case |
Auto case-sensitive if pattern has uppercase | Search Modes §6 |
--word |
Whole-word boundaries (\b…\b) |
Search Modes §7 |
--name-only |
Match filename only, not full path | Search Modes §8 |
--in-path <GLOB> |
Filter by directory path (not filename) | Search Modes §12 |
| Flag | Example | Effect |
|---|---|---|
--drive <X> |
--drive C |
Search single drive |
--drives <X,Y> |
--drives C,D,E |
Search multiple drives concurrently |
| Pattern prefix | c:/*.dll |
Infer drive from pattern |
| Flag | Description |
|---|---|
--mft-file <PATH> |
Use offline raw MFT file(s) instead of live volume |
--data-dir <DIR> |
Auto-discover MFT files in drive_* subdirectories |
--no-cache |
Bypass cache; re-read MFT fresh |
All filters are detailed in the Filters guide. Summary:
| Flag | Category | Quick Description |
|---|---|---|
--files-only |
Scope | Files only |
--dirs-only |
Scope | Directories only |
--hide-system |
Scope | Hide $-prefixed NTFS metadata files |
--hide-ads |
Scope | Hide Alternate Data Stream entries |
--min-size <SIZE> |
Size | Minimum logical size (e.g. 100MB, 1GB) |
--max-size <SIZE> |
Size | Maximum logical size |
--exact-size <SIZE> |
Size | Exactly this size (shorthand for min=max) |
--min-size-on-disk <SIZE> |
Size | Minimum allocated size (concept) |
--max-size-on-disk <SIZE> |
Size | Maximum allocated size |
--exact-size-on-disk <SIZE> |
Size | Exactly this allocated size |
--newer <SPEC> |
Date | Modified within / after |
--older <SPEC> |
Date | Modified before |
--newer-created <SPEC> |
Date | Created within / after |
--older-created <SPEC> |
Date | Created before |
--newer-accessed <SPEC> |
Date | Accessed within / after |
--older-accessed <SPEC> |
Date | Accessed before |
--between <START,END> |
Date | Time range shorthand (e.g. 2026-01-01,2026-03-31) |
--month <SPEC> |
Date | Month-of-year filter (jan, Q1, etc.) |
--attr <LIST> |
Attribute | Require/exclude NTFS attributes |
--type <CATEGORY> |
Type | Semantic type: code, picture, video, … |
--ext <LIST> |
Extension | Filter by extension or collection |
--min-descendants <N> |
Tree | Min child count (dirs) |
--max-descendants <N> |
Tree | Max child count (dirs) |
--exact-descendants <N> |
Tree | Exactly N children |
--min-treesize <SIZE> |
Tree | Min subtree logical size (concept) |
--max-treesize <SIZE> |
Tree | Max subtree logical size |
--min-tree-allocated <SIZE> |
Tree | Min subtree allocated size |
--max-tree-allocated <SIZE> |
Tree | Max subtree allocated size |
--min-bulkiness <N> |
Derived | Min waste ratio (concept) |
--max-bulkiness <N> |
Derived | Max waste ratio |
--min-name-length <N> |
Derived | Min filename character count |
--max-name-length <N> |
Derived | Max filename character count |
--min-path-length <N> |
Derived | Min full-path character count |
--max-path-length <N> |
Derived | Max full-path character count |
--in-path <GLOB> |
Path | Directory path must match glob |
--exclude <GLOB> |
Exclude | Exclude matching filenames |
--malformed |
Forensic | Only ill-formed-UTF-16 names (guide) |
--well-formed |
Forensic | Only valid names (inverse of --malformed) |
--malformed-path |
Forensic | Match when any path segment is ill-formed |
--normalize-malformed |
Forensic | Display: render corrupt code units as <BAD:HHHH> not � |
-n, --limit <N> |
Limit | Max results (0 = unlimited) |
All 36+ sortable columns are detailed in the Sorting guide. Summary:
| Flag | Example | Effect |
|---|---|---|
--sort <SPEC> |
--sort size |
Sort by column (smart default direction) |
--sort <SPEC> |
--sort size:asc,name |
Multi-tier with explicit direction |
--sort-desc |
Flip primary sort direction |
Popular sort columns: size, modified, created, name, ext,
path, treesize, bulkiness, pathlength, namelength,
descendants, type, hidden, compressed, directory_flag.
See Sorting §2 for the full list.
All output options are detailed in the Output Formats guide. Summary:
| Flag | Default | Description |
|---|---|---|
--format <FMT> |
csv |
Output format: csv, json, table, custom |
--columns <LIST> |
all |
Columns to output (comma-separated or all) |
--out <DEST> |
console |
Output destination: console or a filename |
--sep <CHAR> |
, |
Column separator (CSV mode) |
--quotes <CHAR> |
" |
Quote character for string fields |
--header <BOOL> |
true |
Include header row (--header false to suppress) |
--pos <STR> |
1 |
Representation for true/active boolean attributes |
--neg <STR> |
0 |
Representation for false/inactive boolean attributes |
These flags run server-side analytics alongside (or instead of) search
results. For the uffs --agg command, see §6 below.
--statsand--aggare dual-use: as the first token (uffs --stats,uffs --agg <preset>) they are commands; after a pattern (uffs '*.log' --stats size) they are inline modifiers on a search. The first token decides — see CLI Grammar.
| Flag | Effect |
|---|---|
--count |
Show total matching count (suppresses rows) |
--facet <FIELD[:TOP]> |
Top-N breakdown by field (e.g. --facet extension) |
--stats <FIELD> |
Scalar statistics for a numeric field |
--histogram <FIELD[:INTERVAL]> |
Histogram buckets |
--agg <SPEC> |
Raw aggregation spec (power syntax) |
--rows |
Include matching rows alongside aggregates |
--agg-cursor <CURSOR> |
Continue from a previous page |
--agg-page-size <N> |
Max buckets per page |
Full aggregation guide: Aggregation
Building/loading an index is daemon-managed — there is no standalone
uffs indexcommand. Point the daemon at a live drive or a raw MFT withuffs --daemon start --data-dir <dir>/--mft-file <file>(see Daemon). For low-level NTFS volume/record inspection, use the separateuffs-mfttool (uffs-mft --help).
Show file statistics. Without a path, connects to the daemon and
runs the overview aggregate preset. With a path, loads a parquet
index file.
uffs --stats # Daemon mode (live overview)
uffs --stats index.parquet # Parquet mode (--top 20 for largest files)Run server-side analytics on the filesystem index. Returns aggregate results only — no file rows.
uffs --agg overview # Full filesystem overview
uffs --agg by_extension # Top 50 extensions
uffs --agg by_type # Breakdown by file type
uffs --agg by_drive # Per-drive totals
uffs --agg by_size # Size distribution
uffs --agg by_age # Age distribution
uffs --agg count # Simple total countFull guide: Aggregation
Manage the UFFS background daemon. The daemon starts automatically on first search — these commands give explicit control.
uffs --daemon start --data-dir ~/uffs_data # Start with specific data
uffs --daemon status # Check status (short)
uffs --daemon status -v # Long view + performance counters
uffs --daemon status --json # Machine-readable (status+drives+stats)
uffs --daemon stop # Graceful shutdown
uffs --daemon kill # Force kill + cleanup
uffs --daemon restart # Stop then restartFull guide: Daemon
Manage the MCP server for AI agent integration.
uffs --mcp run # Run on stdin/stdout (for AI hosts)
uffs --mcp start # Start HTTP server on :8080 (background)
uffs --mcp start --port 9090 # Custom port
uffs --mcp status # Health + stats
uffs --mcp stop # Graceful shutdown
uffs --mcp reload # Reload all MCP sessions after binary updateFull guide: MCP Server
Show combined system status — daemon + Access Broker + MCP health in one view.
uffs --status # Short: one glyph-led line per component
uffs --status -v # Long: expand every section
uffs --status --json # Machine-readable superset of all sectionsThese flags are for power users, profiling, and parity testing:
| Flag | Description |
|---|---|
-v, --verbose |
Enable verbose output (global) |
--profile |
Show detailed timing breakdown |
--benchmark |
Skip output; measure only MFT reading + filtering |
--no-bitmap |
Disable MFT bitmap optimisation (read ALL records) |
--no-cache |
Bypass cache; re-read MFT fresh |
--query-mode <MODE> |
Force query path: auto, index, dataframe |
--tz-offset <HOURS> |
Override timezone offset for timestamps |
--parity-compat |
C++ parity-compatible output (25 baseline columns) |
Full diagnostics guide: Advanced Diagnostics
For a comprehensive recipe gallery organized by workflow (quick find, cleanup, developer/admin, attribute search, output piping), see Getting Started §5 — Recipes.
Quick taste:
uffs '*.pdf' --newer 7d --sort size --limit 20
uffs '*' --dirs-only --max-descendants 0
uffs '>.*\.log$' --newer 24h