# How to Specify the Career-Ops Data Directory Using Environment Variables

> Learn to specify your career-ops data directory using CAREER_OPS_ROOT or CAREER_OPS_DATA_DIR environment variables. Control tracker path with CAREER_OPS_TRACKER.

- Repository: [Santiago Fernández de Valderrama/career-ops](https://github.com/santifer/career-ops)
- Tags: how-to-guide
- Published: 2026-08-28

---

**Use `CAREER_OPS_ROOT` or `CAREER_OPS_DATA_DIR` to override the default career-ops data directory location, while `CAREER_OPS_TRACKER` provides separate control for the tracker file path.**

By default, the `santifer/career-ops` repository uses its own root as the career-ops data directory, storing files like [`data/applications.md`](https://github.com/santifer/career-ops/blob/main/data/applications.md) within the repository structure. You can redirect all data operations to a custom location using specific environment variables documented across the project's core files.

## Primary Environment Variables for the Data Directory

Career-Ops checks for two interchangeable environment variables that function as aliases for the same purpose. Whichever is defined takes precedence over the default repository root.

### CAREER_OPS_ROOT (Primary Override)

The `CAREER_OPS_ROOT` variable is the primary mechanism for specifying a custom career-ops data directory. When set, its value becomes `{DATA_ROOT}`, and all default data file paths resolve relative to this location. According to [`AGENTS.md`](https://github.com/santifer/career-ops/blob/main/AGENTS.md), this variable "overrides the root path" for all data operations.

### CAREER_OPS_DATA_DIR (Alias)

The `CAREER_OPS_DATA_DIR` variable functions identically to `CAREER_OPS_ROOT`. As documented in [`DATA_CONTRACT.md`](https://github.com/santifer/career-ops/blob/main/DATA_CONTRACT.md), either variable can be set to "the absolute or relative path of your custom data directory." If both are present, the system uses whichever is defined, applying the same resolution logic to establish the data root.

## How the Override Logic Works

The precedence and resolution logic implemented in [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md) follows this sequence:

1. The system checks for the presence of `CAREER_OPS_ROOT` or `CAREER_OPS_DATA_DIR`.
2. If either is defined, the value is resolved relative to the repository root when given as a relative path.
3. The resolved path becomes `{DATA_ROOT}`, used to locate [`data/applications.md`](https://github.com/santifer/career-ops/blob/main/data/applications.md), [`data/pipeline.md`](https://github.com/santifer/career-ops/blob/main/data/pipeline.md), and other default files.
4. If neither variable is set, Career-Ops falls back to using the repository root as the data directory.

## Overriding the Tracker File Specifically

While the primary variables change the entire career-ops data directory, you can override only the tracker file path using `CAREER_OPS_TRACKER`. As noted in [`AGENTS.md`](https://github.com/santifer/career-ops/blob/main/AGENTS.md), this variable does **not** change the overall data directory—it only redirects where the system reads and writes the applications tracker. This is useful when you want to keep most data in the default location but store the tracker elsewhere.

```bash

# Override only the tracker file path

export CAREER_OPS_TRACKER=$HOME/documents/applications.md

```

## Practical Configuration Examples

### Linux and macOS (Bash)

Set the environment variable in your shell configuration or current session:

```bash

# Set a custom data directory using the primary variable

export CAREER_OPS_ROOT=$HOME/my-career-data

# Or use the alias variable with identical effect

export CAREER_OPS_DATA_DIR=$HOME/my-career-data

```

### Windows (PowerShell)

Configure the variable in your PowerShell session or profile:

```powershell

# Primary variable

$env:CAREER_OPS_ROOT = "$HOME\my-career-data"

# Alias variable

$env:CAREER_OPS_DATA_DIR = "$HOME\my-career-data"

```

### Running Commands with Custom Paths

Once exported, all Career-Ops commands automatically use the specified directory:

```bash

# Scanner will read/write under $CAREER_OPS_ROOT/data/

career-ops scan

# Pipeline operations use the custom root for data/pipeline.md

career-ops pipeline status

```

## Where These Variables Are Documented

The environment variable behavior is formally specified across several source files:

- **[`AGENTS.md`](https://github.com/santifer/career-ops/blob/main/AGENTS.md)** – Provides an overview of `CAREER_OPS_ROOT` and `CAREER_OPS_TRACKER` overrides.
- **[`README.md`](https://github.com/santifer/career-ops/blob/main/README.md)** – Contains quick-start instructions mentioning both primary variables.
- **[`DATA_CONTRACT.md`](https://github.com/santifer/career-ops/blob/main/DATA_CONTRACT.md)** – Defines the formal data contract for variable usage and path resolution.
- **[`docs/SCRIPTS.md`](https://github.com/santifer/career-ops/blob/main/docs/SCRIPTS.md)** – Documents script-level implementations of all environment variables.
- **[`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md)** – Implements the runtime logic that checks variable precedence and resolves paths.

## Summary

- **Primary variables**: `CAREER_OPS_ROOT` and `CAREER_OPS_DATA_DIR` are interchangeable aliases that specify the career-ops data directory.
- **Resolution**: Values are resolved relative to the repository root if not absolute, as implemented in [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md).
- **Fallback**: If no variables are set, the system uses the repository root containing the code.
- **Tracker-specific**: `CAREER_OPS_TRACKER` overrides only the tracker file path without affecting the broader data directory structure.

## Frequently Asked Questions

### What is the difference between CAREER_OPS_ROOT and CAREER_OPS_DATA_DIR?

There is no functional difference between these variables. They are aliases that serve the same purpose of specifying the career-ops data directory. The system checks for either one and applies the same resolution logic, as documented in [`DATA_CONTRACT.md`](https://github.com/santifer/career-ops/blob/main/DATA_CONTRACT.md) and implemented in [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md).

### Can I use a relative path for the career-ops data directory?

Yes. When you provide a relative path to `CAREER_OPS_ROOT` or `CAREER_OPS_DATA_DIR`, the system resolves it relative to the repository root. For example, setting the variable to `../my-data` would place the data directory at the same level as the repository folder.

### How do I override only the tracker file location without changing the data directory?

Set the `CAREER_OPS_TRACKER` environment variable to the specific path of your tracker file (e.g., [`data/applications.md`](https://github.com/santifer/career-ops/blob/main/data/applications.md)). This overrides only the tracker file location, leaving other data files like [`data/pipeline.md`](https://github.com/santifer/career-ops/blob/main/data/pipeline.md) in their default or custom data directory locations.

### What happens if no environment variables are set?

If neither `CAREER_OPS_ROOT` nor `CAREER_OPS_DATA_DIR` is defined, Career-Ops defaults to using the repository root as the data directory. All file operations for [`data/applications.md`](https://github.com/santifer/career-ops/blob/main/data/applications.md), [`data/pipeline.md`](https://github.com/santifer/career-ops/blob/main/data/pipeline.md), and other default paths occur within the repository structure itself.