# ORX Data Directory Resolution Order: How OpenResearch Locates Your Data

> Understand the ORX data directory resolution order. Learn how OpenResearch finds your data by checking ORX_DATA_DIR, XDG_DATA_HOME, and your home directory.

- Repository: [alphaXiv/OpenResearch](https://github.com/alphaXiv/OpenResearch)
- Tags: how-to-guide
- Published: 2026-09-13

---

**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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/src/store.rs):

```rust
//! 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`](https://github.com/alphaXiv/OpenResearch/blob/main/src/store.rs), the actual path resolution logic lives in module helpers.

### Source Documentation

The module-level documentation in [`src/store.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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:

```rust
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`](https://github.com/alphaXiv/OpenResearch/blob/main/src/store.rs) and implemented in [`src/local/datadir.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/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:

```bash
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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`.