To see which files in your inbox have exceeded the age_threshold_days, run:

relfa scan

This will print a list of "stale" files and another list of files that are old enough to be auto-archived. This command is read-only and will not modify any files.

For a guided, one-by-one review of your stale files, run:

relfa review

For each file, you will be prompted to choose an action:

• (a)rchive: Move the file to the graveyard.
• (n)ote+archive: Archive the file and attach an epitaph (a descriptive note).
• (t)ouch: Update the file's modification time to keep it for another period.
• (d)elete: Permanently delete the file (requires confirmation).
• (v)iew: Preview the file's content using your configured pager.
• (o)pen: Open the file with its default application.
• (s)kip: Do nothing and move to the next file.
• (q)uit: Exit the review session.
• (?)help: Show a detailed help message with all available actions.

The archive command is flexible and has several modes.

Auto-Archiving

To automatically archive all files that have exceeded the auto_archive_threshold_days, simply run archive with no arguments:

# Archives all files older than the "hard limit" threshold.
relfa archive

# You can also add a note to all auto-archived files.
relfa archive --note "Weekly automated cleanup"

Archiving Specific Files or All Stale Files

# Archive a single, specific item from your inbox.
relfa archive "my-old-document.pdf" --note "Final version, no longer needed."

# Archive all stale files (those older than the "soft limit").
relfa archive --all

To find files you've already archived, use the search command. It searches both filenames and epitaph content.

relfa search "project-alpha"

To bring a file back from the graveyard to your inbox, use resurrect. This copies the file back, leaving the original in the graveyard.

relfa resurrect "important-document.pdf"

If your search term matches multiple files, Relfa will present a list for you to choose from.

The recommended way to use Relfa is declaratively through its Home Manager module, which allows for easy configuration and automated execution. See the Home Manager Configuration section for details.

For quick trials or environments without Home Manager, you can use one of the following nix commands:

Temporary Execution

To run Relfa without installing it, use nix run:

nix run github:nilp0inter/relfa -- [command]
# Example:
nix run github:nilp0inter/relfa -- scan

Persistent Installation

To install Relfa into your user profile, making it available in your shell, run:

nix profile install github:nilp0inter/relfa

If you have the Rust toolchain installed on your system, you can install Relfa directly from crates.io using cargo:

cargo install relfa

This command will download the source code, compile it, and place the relfa binary in your Cargo binary path (~/.cargo/bin/), which should be in your system's PATH.

Pre-compiled binaries are available for Linux and macOS from the releases page.

Supported Platforms:

• Linux x86_64 (relfa-VERSION-x86_64-unknown-linux-musl)
• macOS Intel (relfa-VERSION-x86_64-apple-darwin)
• macOS Apple Silicon (relfa-VERSION-aarch64-apple-darwin)

Installation:

1. Download the appropriate binary for your platform from the latest release
2. Make it executable: chmod +x relfa-*
3. Copy it to a directory in your PATH: cp relfa-* ~/.local/bin/relfa (or /usr/local/bin/relfa)

If you need binaries for other platforms, please open an issue on GitHub.

Relfa is configured via a TOML file located at ~/.config/relfa/config.toml.

You can generate a configuration file with default values by running:

relfa config

This will create the file if it doesn't exist and print the current settings.

Example config.toml

# Path to the directory you want Relfa to monitor.
inbox = "/home/user/Inbox"

# Path to the directory where archived files will be stored.
graveyard = "/home/user/Graveyard"

# (Soft limit) Files older than this (in days) are considered "stale"
# and will be shown during a `scan` or `review`.
age_threshold_days = 3

# (Hard limit) Files older than this (in days) will be automatically
# archived when you run `relfa archive` without any arguments.
auto_archive_threshold_days = 7

# Minimum number of times a file must be notified to the user
# before it becomes eligible for auto-archiving. Protects against
# auto-archiving on computers that are used sporadically.
auto_archive_min_scans = 24

# How to deliver notifications. Can be "cli" or "desktop".
notification = "desktop"

# The command to use for viewing files with the `review` command.
# Defaults to your $PAGER environment variable, or "less".
pager = "less"

# Configuration for the graveyard's directory structure.
[path_format]
# A template for creating date-based paths.
# Available variables: {hostname}, {year}, {month}, {day}, {month:02}, {day:02}
date_format = "{hostname}/{year}/{month:02}/{day:02}"

# Defines a subdirectory for organizing files by their creation date.
# `type = "original"` means the actual files are stored here.
[path_format.created_subdir]
type = "original"
name = "created"

# Defines a subdirectory for organizing files by their modification date.
# `type = "symlink"` means this directory will contain symbolic links.
# `target = "created"` means the links will point to the files in the "created" subdirectory.
[path_format.modified_subdir]
type = "symlink"
name = "modified"
target = "created"

# Defines a subdirectory for organizing files by their archival date.
# In this example, this view is disabled.
[path_format.archived_subdir]
type = "nothing"

For users of Nix and Home Manager, Relfa provides a module for declarative configuration.

1. Add the flake to your inputs:

   # flake.nix
   {
     inputs = {
       relfa.url = "github:nilp0inter/relfa";
       # ... other inputs
     };
   }
   

2. Import the module in your home.nix:

   { inputs, ... }: {
     imports = [ inputs.relfa.homeManagerModules.relfa ];
   }
   

3. Configure Relfa:

   The programs.relfa.settings block is required for the program to run. Note that the path_format section and its sub-sections are also mandatory.

   # home.nix
   programs.relfa = {
     enable = true;
   
     settings = {
       inbox = "${config.home.homeDirectory}/Downloads";
       graveyard = "${config.home.homeDirectory}/Archive";
       age_threshold_days = 5;
       auto_archive_threshold_days = 14;
       auto_archive_min_scans = 24;
       notification = "desktop";
   
       # The `path_format` block is required.
       path_format = {
         date_format = "{hostname}/{year}/{month:02}/{day:02}";
         created_subdir = {
           type = "original";
           name = "created";
         };
         modified_subdir = {
           type = "symlink";
           name = "modified";
           target = "created";
         };
         archived_subdir = {
           type = "symlink";
           name = "archived";
           target = "created";
         };
       };
     };
   
     # Optional: Enable a systemd timer for automated execution.
     timer = {
       enable = true;
       # Run `relfa scan` daily.
       command = "scan";
       frequency = "daily";
       # Add a random delay to avoid running at the exact same time as other services.
       randomizedDelay = "1h";
     };
   };
   

Timer Options

The timer submodule allows you to automate Relfa's execution.

• command: Which command to run. Can be "scan", "archive", or "scan-then-archive".
• frequency: How often to run the command. Accepts systemd.time calendar event formats (e.g., "daily", "hourly", "*:0/30" for every 30 minutes).
• randomizedDelay: A random delay to add before execution (e.g., "1h", "30m").

The official and recommended development setup for Relfa uses Nix and Direnv. While other setups are possible, they are not officially supported and are left to the user's discretion.

Prerequisites

Before you begin, ensure you have both Nix and Direnv installed on your system.

Setup

Setting up the development environment is a one-step process. Simply navigate to the project's root directory in your terminal and run:

direnv allow

This command will trigger the Nix flake to build the complete development environment. It automatically:

• Downloads and installs all necessary dependencies (Rust toolchain, etc.).
• Configures and installs the required Git hooks.
• Activates a devshell with pre-configured aliases for common tasks (build, test, format, etc.).

Workflow

Once the environment is active, you will have access to a devshell menu with commands for building, testing, and formatting the code.

The installed Git hooks will run automatically on every commit. These hooks check for correct formatting and ensure the project compiles, helping to guarantee that your changes will pass the CI pipeline.