Querying

Atlas provides several commands for finding files, exploring history, and understanding activity across your tracked files.

Quick Status

Running atlas with no arguments gives a compact one-line summary of what Atlas is tracking:

atlas

For the full status view with daemon info, watched paths, and entity counts:

atlas status

Finding Files

Search

Search for entities by name, path, or hash prefix:

atlas search "config"
atlas search "README"
atlas search "4a7f3b"

Search checks both current and historical values, so you can find a file even if it’s been renamed.

Scope results to a specific directory:

atlas search "config" --in ~/projects/myapp

Find

Find entities with specific criteria:

atlas find --hash "a7f3b2c1d9e8f7a6..."
atlas find --name "config.json"
atlas find --path "/home/user/projects"

Multiple criteria can be combined to narrow results. Add --json for machine-readable output.

Filter by Status

Show entities in a specific state:

atlas find --status deleted        # Files Atlas lost track of
atlas find --status disconnected   # Files on unmounted drives
atlas find --status live           # Active files (default behavior)

Combine with other criteria:

atlas find --path "/Volumes/MyDrive" --status deleted
atlas find --name "config.json" --status live

Results are limited to 1000 entries.

Filtered Find (MCP)

When using Atlas via the MCP server, atlas_find supports additional filtering parameters for precise queries:

• extension — Filter by file extension (e.g., .RPP, wav)
• path_contains — Filter by path substring (e.g., /_Projects/2025/)
• exclude — Exclude names matching a LIKE pattern (e.g., %.RPP-BAK)
• date_from / date_to — Filter by date range (RFC 3339, e.g., 2025-01-01T00:00:00Z)
• witnessed_only — Only include entities Atlas directly observed (not discovered during initial scan)
• limit / offset — Pagination to control result size

These filters prevent oversized results when searching large collections. The date_from/date_to parameters filter on the entity’s created_at timestamp. The witnessed_only flag excludes entities found during initial scans, whose timestamps reflect scan time rather than actual file creation time.

Find Duplicates

Find all files that share the same content hash (identical files in different locations):

atlas find --duplicates

Output groups files by hash:

Found 3 groups of duplicate files:

Hash: 4a7f3b2c1d9e8...
  /path/to/file1.txt (file1.txt)
  /path/to/backup/file1.txt (file1.txt)

Find Orphans

Find files that nothing references — potential dead weight:

atlas find --orphans

Filter by file extension:

atlas find --orphans --ext css    # Unused CSS files
atlas find --orphans --ext js     # Unused JavaScript files

File History

View the complete lifecycle of a specific file:

atlas history ~/projects/myapp/README.md

You can also use an entity ID:

atlas history a1b2c3d4-e5f6-47a8-9f0b-1c2d3e4f5a6b

History shows:

• Current name, path, hash, and status (active, deleted, or disconnected)
• Fork information (if this file was copied from another)
• Entity ID
• Complete timeline of all changes: creation, modifications, renames, moves, deletions, and disconnections

Directory History

Pass a directory to see recent activity across all files in that directory:

atlas history ~/projects/myapp/

This shows changes grouped by entity, so you can see which files in the directory have been most active.

Fork Tree

Visualize all copies of a file and how they’ve diverged:

atlas tree ~/projects/styles.css

This shows the fork tree as an ASCII diagram — the original file, every copy, and where they branched. Add --json for machine-readable output.

Activity Log

See recent changes across all tracked files:

atlas log

Options:

atlas log -n 50                    # Show 50 entries (default: 20)
atlas log --today                  # Only today's activity
atlas log --entity ~/projects/app  # Filter to specific file

The log groups entries by day and shows the action type (created, modified, renamed, moved, deleted). Timestamps for entities discovered during an initial scan (rather than witnessed in real-time) are prefixed with ~ to indicate the timestamp reflects when Atlas scanned the file, not when it was originally created.

Via MCP, atlas_log also supports date_from, date_to, and witnessed_only parameters for temporal filtering.

Daily Summary

View a summary of activity grouped by day:

atlas log --summary
atlas log --summary --days 30              # Last 30 days (default: 7)
atlas log --summary --path ~/projects      # Filter to directory

Output:

Mar 10 2025 | 5 new, 12 modified, 2 deleted
Mar 09 2025 | 3 new, 8 modified
Mar 08 2025 | 15 new, 1 forked

Statistics

View database-level statistics:

atlas stats

Shows entity counts (active and deleted), number of watched paths, and database file size.

Scope stats to a specific directory:

atlas stats ~/projects/myapp

This shows entity count and edge count for files within that directory.

Comparing Files and Directories

Compare two files or directories using Atlas’s content-identity model:

atlas compare ~/file-a.txt ~/file-b.txt
atlas compare ~/project-v1/ ~/project-v2/

File Comparison

Compares content (by hash), names, and lineage between two files:

Comparing: file-a.txt ↔ file-b.txt

  Content:  identical (4a7f3b2c...)
  Names:    different (file-a.txt vs file-b.txt)
  Related:  forked (common ancestor from Mar 3)

Atlas detects whether two files share lineage (one was copied from the other), not just whether the bytes match.

Directory Comparison

Compares all files in two directories using a four-layer matching model:

1. Identical content — same BLAKE3 hash, regardless of name or location
2. Diverged forks — shared lineage but content has changed since
3. Name collisions — same path and name, unrelated content
4. Unmatched — exists in only one side

Comparing: ~/project-v1/ ↔ ~/project-v2/

  82% identical by content. 50 matched, 8 diverged, 5 only in left, 3 only in right.

  Relocated directories:
    components/  →  ui/ (12 files)

  Renamed/relocated (same content):
    kick_v3_final.wav ↔ Client_Kick.wav (renamed)

  Diverged (shared lineage, content differs):
    config.json — diverged since Mar 1

  Only in project-v1/ (5 files):
    old-module.rs
    ...

Atlas groups files whose parent directory was renamed (structural rename detection) rather than listing each file individually.

Options

Flag	Description
--verbose	Show all files including identical matches
--allow-untracked	Compare paths Atlas doesn’t currently watch (hashes computed on the fly)
--names-only	Only report name and path differences
--content-only	Only report content differences
--json	Machine-readable JSON output

By default, both paths must be tracked by Atlas. Use --allow-untracked to compare untracked directories (lineage information won’t be available for untracked files).

JSON Output

All query commands support --json for machine-readable output:

atlas status --json
atlas history ~/README.md --json
atlas find --name "config" --json
atlas find --duplicates --json
atlas tree ~/styles.css --json
atlas log --json
atlas log --summary --json
atlas compare ~/v1/ ~/v2/ --json

See JSON Output for details on integrating Atlas with other tools.