Getting Started

Atlas is a local-first file lineage engine. It watches directories you choose, hashes file contents with BLAKE3, and builds a graph of how your files relate — tracking every version, copy, reference, and origin across your filesystem. All data stays on your machine.

Installation

Build Atlas from source:

git clone https://github.com/fileatlas/atlas-v2.git
cd atlas-v2
cargo build --release

The binary is built to target/release/atlas-v2. Add it to your PATH or copy it somewhere convenient:

cp target/release/atlas-v2 /usr/local/bin/atlas

Shell Completions

Generate completions for your shell:

atlas completions bash > ~/.bash_completion.d/atlas
atlas completions zsh > ~/.zsh/completions/_atlas
atlas completions fish > ~/.local/share/fish/vendor_completions.d/atlas.fish

macOS: Grant Full Disk Access

Atlas uses macOS filesystem events to detect changes in real time. For this to work, the app that launches Atlas (typically Terminal or iTerm) needs Full Disk Access.

  1. Open System Settings → Privacy & Security → Full Disk Access
  2. Toggle on your terminal app (e.g. Terminal, iTerm2, Warp)
  3. Restart your terminal

Without this, the Atlas daemon will start and appear healthy, but will silently miss file changes. If you grant access while the daemon is already running, restart it with atlas stop && atlas start.

Tip: If atlas history returns empty for a directory you know has files, run atlas scan to discover them manually, then restart the daemon to fix real-time tracking.

First Run

The first time you run atlas watch, Atlas asks for your consent before storing any data:

Welcome to Atlas.

Atlas tracks file metadata (names, paths, content hashes) and reads
supported file formats to discover references between files. All data is
stored in a local SQLite database at ~/.atlas/atlas.db. No file contents
are stored — only hashes and extracted references. All data stays on your machine.

Continue? [Y/n]

Accept to proceed. Atlas creates its data directory at ~/.atlas/ and initializes the database.

Watch a Directory

Tell Atlas which directories to track:

atlas watch ~/projects/myapp

Atlas immediately scans the directory, hashes every file, and begins tracking. It also starts the background daemon automatically so changes are picked up in real time.

You can watch as many directories as you want:

atlas watch ~/Documents
atlas watch ~/music/sessions

Or watch a single file:

atlas watch ~/important-config.yaml

Check Status

Run atlas with no arguments for a quick one-line summary:

atlas

Or get the full status view:

atlas status

This shows whether the daemon is running, which paths are watched, and how many files are tracked.

View Activity

See recent changes across all tracked files:

atlas log

Or get a daily activity summary:

atlas log --summary

Look at the full history of a specific file or directory:

atlas history ~/projects/myapp/README.md
atlas history ~/projects/myapp/

Stop Watching

Remove a directory from the watch list:

atlas unwatch ~/projects/myapp

This stops tracking new changes but preserves all existing history.

Daemon Control

Atlas runs a background daemon to watch for file changes. It starts automatically when you atlas watch, but you can also manage it directly:

atlas start          # Start the daemon
atlas stop           # Stop the daemon
atlas start --boot   # Start on login (macOS)
atlas stop --boot    # Remove from login startup

What’s Next