User Guide

User Guide

This is the quick orientation page for anyone who wants the *arr mental model first and the implementation details second.

Web UI Layout

Symlinkarr groups the UI the same way an *arr user expects to navigate:

Overview

• Dashboard: compact summary of current state

Activity

• Scan: preview or apply source-to-library linking work
• Status: health, queue pressure, dead-link signal, and integration state
• Links: review current link state

Maintenance

• Cleanup: build audit reports and preview prune work
• Doctor: preflight checks for config, paths, and permissions
• Discover: read-only preview of likely placements for underlinked folders

System

• Backup: create, inspect, and restore Symlinkarr backups and restore points
• Config: validate and review the active configuration

What To Use For What

Use Scan when:

• new content arrived
• the library looks underlinked
• you want the normal day-to-day linking flow

Use Repair or Dead Links when:

• symlinks point to missing files
• you want safe relinking instead of a full scan-first approach

Use Cleanup when:

• the library has stale, foreign, or legacy link leftovers
• you want a report before deleting anything

Use Discover when:

• tagged folders still look sparse or empty
• you want a placement preview without applying it

Use Doctor when:

• the stack feels wrong before a run even starts
• mounts, permissions, secrets, or database state may be off

Backup Types

Symlinkarr uses two backup names on purpose:

• Symlinkarr Backup: the main backup to keep. It includes the tracked-link manifest, a sibling SQLite snapshot, and app-state snapshots for the active config and any secretfile: secrets the install can see.
• Restore Point: a lighter rollback point created around repair, cleanup, or daemon work.

Important:

• restoring a Symlinkarr Backup can put link state, SQLite state, config, and secretfile: secrets back onto the current install
• environment-only secrets still live outside the backup set
• a fresh install still needs its config and secrets placed before first startup

Advanced Toggle

The UI intentionally hides more detailed diagnostics behind Advanced.

That means:

• the default view stays fast to scan
• routine actions stay visible first
• deeper telemetry is still there when something needs debugging

Key Expectations

• scan --dry-run should be your normal first move
• discover in the web UI is preview-only
• cleanup is report-first, not blind deletion
• media-server refresh is supporting behavior, not the product itself