ORX Data Directory Resolution Order: How OpenResearch Locates Your Data

The orx CLI resolves the data directory by checking $ORX_DATA_DIR first, then $XDG_DATA_HOME/openresearch, and finally falling back to $HOME/.local/share/openresearch.

OpenResearch (alphaXiv/OpenResearch) follows the XDG Base Directory Specification with custom environment overrides to determine where project data lives. Understanding this orx data directory resolution order is essential for backing up your work, migrating between machines, or running isolated instances.

The Three-Level Resolution Hierarchy

The resolution logic is documented in the opening lines of src/store.rs. The system evaluates candidates in strict priority order, returning the first valid path found.

1. Environment Variable Override (ORX_DATA_DIR)

The highest priority is given to the ORX_DATA_DIR environment variable. If this variable is set, its value is used exactly as specified, bypassing all other checks.

According to the source documentation in src/store.rs:

//! Data dir: `$ORX_DATA_DIR`, else `$XDG_DATA_HOME/openresearch`, else
//! `$HOME/.local/share/openresearch`.

When ORX_DATA_DIR is present, the UI treats this as a "pin" and disables the data directory field in settings, preventing accidental overrides through the graphical interface.

2. XDG Data Home (XDG_DATA_HOME)

If ORX_DATA_DIR is unset, the system checks for XDG_DATA_HOME, following the XDG Base Directory Specification. The effective path becomes $XDG_DATA_HOME/openresearch.

If XDG_DATA_HOME is not defined, the XDG specification defaults to $HOME/.local/share, which leads to the final fallback.

3. Platform Default ($HOME/.local/share/openresearch)

When neither environment variable is available, the system defaults to $HOME/.local/share/openresearch. This aligns with standard Unix conventions for user-specific data files.

Implementation Details

While the public API surface documents the contract in src/store.rs, the actual path resolution logic lives in module helpers.

Source Documentation

The module-level documentation in src/store.rs (lines 1–2) serves as the canonical reference for the resolution order. This docstring is the first line of defense for developers seeking to understand data directory placement.

Helper Functions

The src/local/datadir.rs file contains the implementation details that evaluate this precedence chain at runtime. These helpers are shared between the CLI and UI components to ensure consistent behavior across interfaces.

Configuration and Cache Parallels

The same precedence pattern applies to configuration and cache directories, using different environment variable prefixes:

• Config: $ORX_CONFIG_DIR → $XDG_CONFIG_HOME/openresearch
• Cache: $ORX_CACHE_DIR → $XDG_CACHE_HOME/openresearch

However, the orx data directory resolution order specifically concerns the storage location for your research projects and metadata.

Practical Code Example

The following Rust logic mirrors the implementation used in the OpenResearch codebase:

use std::env;
use std::path::PathBuf;

/// Returns the resolved data directory following the orx precedence rules.
fn data_dir() -> PathBuf {
    // Priority 1: Explicit environment override
    if let Some(dir) = env::var_os("ORX_DATA_DIR") {
        return PathBuf::from(dir);
    }

    // Priority 2: XDG Base Directory specification
    if let Some(xdg) = env::var_os("XDG_DATA_HOME") {
        let mut path = PathBuf::from(xdg);
        path.push("openresearch");
        return path;
    }

    // Priority 3: Standard fallback location
    let home = env::var_os("HOME")
        .expect("HOME environment variable must be set");
    let mut path = PathBuf::from(home);
    path.push(".local/share/openresearch");
    path
}

Running this under different conditions demonstrates the resolution behavior:

Environment Variables Set	Resulting Path
ORX_DATA_DIR=/mnt/data	/mnt/data
XDG_DATA_HOME=$HOME/custom (no ORX_DATA_DIR)	$HOME/custom/openresearch
None	$HOME/.local/share/openresearch

Summary

• ORX_DATA_DIR takes absolute precedence over all other locations.
• $XDG_DATA_HOME/openresearch is the secondary fallback for XDG-compliant systems.
• $HOME/.local/share/openresearch is the final default for standard Unix environments.
• The resolution logic is documented in src/store.rs and implemented in src/local/datadir.rs.
• Setting ORX_DATA_DIR "pins" the location, disabling UI overrides.

Frequently Asked Questions

What happens if both ORX_DATA_DIR and XDG_DATA_HOME are set?

The ORX_DATA_DIR variable always wins. As implemented in the OpenResearch source code, the system checks for this environment variable first and returns immediately if found, never evaluating the XDG path.

How can I temporarily change the data directory for a single command?

Prefix your command with the environment variable:

ORX_DATA_DIR=/tmp/orx_test orx list

This follows the standard Unix pattern for per-command environment overrides without affecting your shell session.

Does the graphical UI follow the same resolution order as the CLI?

Yes. Both the CLI and UI share the same core resolution logic from src/store.rs. However, when ORX_DATA_DIR is set, the UI detects this "pin" and disables the data directory field in Settings to prevent conflicts between the environment and user interface.

Where is the resolution order documented in the source code?

The canonical documentation appears in the module-level docstring at the top of src/store.rs (lines 1–2). This file explicitly lists the three-tier precedence: $ORX_DATA_DIR, else $XDG_DATA_HOME/openresearch, else $HOME/.local/share/openresearch.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}