Edges & Lineage

Edges are the structural connections in Atlas’s lineage graph. When Atlas scans tracked files, it discovers which files reference, import, or depend on other files and records these as edges. Combined with fork links, edges let you trace a file’s full origin story — or see the downstream impact of any change.

Inputs — What a File Needs

atlas inputs ~/projects/myapp/index.html

Shows all files that the given file references — its inputs. Results are grouped by file type (audio, plugins, stylesheets, images, code, etc.).

Directory Inputs

Pass a directory to see all inputs for every file in that directory:

atlas inputs ~/projects/myapp/

Output is split into sections:

• External — files outside the directory that something inside depends on
• Internal — files inside the directory that reference each other
• Broken — references that couldn’t be resolved

Filter to only external dependencies:

atlas inputs ~/projects/myapp/ --external

Outputs — What a File Produces

atlas outputs ~/music/sessions/my-song.rpp

Shows files that this file produces (e.g., render outputs from a DAW project). This represents authorship — what did this file create?

Directory Outputs

atlas outputs ~/music/sessions/
atlas outputs ~/music/sessions/ --external

Same external/internal/broken split as directory inputs.

Impact Analysis

See the full cascade of files affected if a given file changes:

atlas impact ~/projects/myapp/styles.css

This walks the graph to show every file that directly or indirectly depends on the target. Useful before making changes to shared files.

Options

atlas impact ~/projects/myapp/styles.css --depth 1       # Direct dependents only
atlas impact ~/projects/myapp/styles.css --depth 3       # Up to 3 hops
atlas impact ~/projects/myapp/ --external                # Only external impact

Flag	Description
--depth N	Maximum traversal depth (1 = direct dependents only)
--external	Show only external impact (outside the target directory)

Directory Impact

Pass a directory to see what’s affected if anything in that directory changes:

atlas impact ~/projects/myapp/

Output is split into external and internal sections.

Broken References

Find references that point to files Atlas can’t locate:

atlas broken

Scope to a specific file or directory:

atlas broken ~/projects/myapp/index.html
atlas broken ~/projects/myapp/

Lineage Tracing

The atlas trace command walks the full lineage graph — fork links, input/output edges, and source_path breadcrumbs — to answer two core questions:

• Where did this file come from? (backward trace, the default)
• What did this file become? (forward trace)

Backward Trace (Provenance)

atlas trace ~/Deliverables/Client_Kick.wav

Walks inbound relationships to show the file’s full origin story: what it was forked from, what produced it, and what inputs were involved.

Forward Trace (Lineage)

atlas trace ~/Samples/kick.wav --forward

Walks outbound relationships to show everywhere a file ended up: forks, projects that use it, outputs that resulted from it.

Directory Tracing

Pass a directory to trace all files under it:

atlas trace ~/Samples/ --forward --reaches ~/Deliverables/

This answers “which files in /Samples/ resulted in files in /Deliverables/?” — a directory-to-directory lineage query.

Options

Flag	Description
--forward	Trace forward: what did this file become?
--backward	Trace backward: where did this file come from? (default)
--depth N	Limit traversal to N hops from the starting entity
--reaches <path>	Only show lineage chains that reach the given path or directory
--verbose	Show full tree output when it would otherwise be auto-truncated
--json	Structured JSON output for programmatic consumption

When the output exceeds 50 lines, trace automatically switches to a summary view showing endpoints and hop counts. Use --verbose to see the full tree.

Edge Types

Atlas records two types of edges:

Type	Direction	Description	Example
input	This file needs that file	File path reference, import, linked asset	HTML src="logo.png", CSS @import, Reaper FILE directive
output	This file produces that file	Render or export output	DAW render target

Display grouping (plugins, audio files, stylesheets, etc.) is derived from file extensions at render time — it’s a presentation concern, not stored in the database.

Source Path

When an extractor discovers where a file was originally imported from (e.g., Reaper’s ORIGINAL_FILENAME), Atlas records this as a source_path on the target entity rather than as an edge. This provides provenance breadcrumbs without cluttering the edge graph.

Scanning for Edges

Run a scan to extract references from tracked files:

atlas scan

This processes all tracked files through Atlas’s extractor system, looking for references like HTML src attributes, CSS @import statements, audio project file references, and more.

You can limit the scan to a specific path:

atlas scan ~/projects/myapp
atlas scan ~/projects/myapp/index.html

Atlas records what it finds in the database. Subsequent scans update references when file content changes.

Supported Formats

Atlas ships with two extractor packs:

• Core Pack — HTML, CSS, Markdown, SVG, JSON, YAML
• Atlas Audio Pack:
  • Reaper Extractor — DAW project files (.rpp), render outputs
  • Kontakt Extractor — Instrument files (.nki)
  • Plugin Formats — VST, VST3, AU, AAX, CLAP plugin metadata
  • WAV Metadata — BWF/BEXT render provenance (.wav)

See Extractors Overview for how the system works.