# How to Point Career-Ops to an External Data Directory: Complete Configuration Guide

> Learn how to point career-ops to an external data directory using environment variables or a marker file. Configure your repository easily with this complete guide.

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

---

**You can redirect Career-Ops to any external data directory by setting the `CAREER_OPS_ROOT` or `CAREER_OPS_DATA_DIR` environment variable, or by placing a `.career-ops-data` marker file in the repository root.**

Career-Ops maintains strict separation between application code and personal data (CVs, trackers, reports) through a configurable path resolution system. By default, the tool looks for data adjacent to the repository root, but the `path-resolver.mjs` module allows complete redirection to external storage locations. This guide explains how to point Career-Ops to an external data directory using environment variables or marker files based on the santifer/career-ops source code.

## Environment Variable Configuration

The primary mechanism for specifying an external data directory uses environment variables checked at module load time. In `path-resolver.mjs`, the resolver evaluates `process.env.CAREER_OPS_ROOT?.trim() || process.env.CAREER_OPS_DATA_DIR?.trim()` to determine the data location.

### Using CAREER_OPS_ROOT

The `CAREER_OPS_ROOT` variable takes highest priority in the resolution order. When this variable is set, Career-Ops uses its value as the base path for all data read and write operations.

### Absolute vs. Relative Path Resolution

Career-Ops handles path resolution differently based on format:

- **Absolute paths** (starting with `/` on Unix or drive letter on Windows) are used exactly as specified
- **Relative paths** are resolved against the repository root directory

### Fallback to CAREER_OPS_DATA_DIR

If `CAREER_OPS_ROOT` is unset, the resolver automatically checks `CAREER_OPS_DATA_DIR` as a secondary option. Both variables accept the same path formats and follow identical resolution rules.

## Marker File Method

When neither environment variable is present, Career-Ops checks for a `.career-ops-data` file placed in the repository root. This plain text file contains either an absolute or relative path to your external data directory.

This approach persists across shell sessions without requiring exports, making it suitable for project-specific configurations stored in version control (if the data path is consistent across machines).

## Configuration Code Examples

Set an absolute path to external storage:

```bash
export CAREER_OPS_ROOT=/home/you/career-data
career-ops scan

```

Use a relative path resolved against the repository:

```bash
export CAREER_OPS_DATA_DIR=../my-career-data
career-ops pipeline

```

Create the marker file for persistent configuration:

```bash
echo "/mnt/external/career-data" > .career-ops-data
career-ops add

```

## Configuration Precedence and Documentation

The resolution order is explicitly defined in [`AGENTS.md`](https://github.com/santifer/career-ops/blob/main/AGENTS.md) and implemented in `path-resolver.mjs`:

1. `CAREER_OPS_ROOT` environment variable
2. `CAREER_OPS_DATA_DIR` environment variable  
3. `.career-ops-data` marker file contents
4. Default location adjacent to repository root

The [`DATA_CONTRACT.md`](https://github.com/santifer/career-ops/blob/main/DATA_CONTRACT.md) file formally specifies these variables as part of the official configuration interface, while the [`README.md`](https://github.com/santifer/career-ops/blob/main/README.md) provides user-facing documentation with export examples.

## Summary

- **Set `CAREER_OPS_ROOT`** to specify an external data directory with highest priority
- **Use `CAREER_OPS_DATA_DIR`** as an alternative environment variable if the primary is unavailable
- **Place a `.career-ops-data` file** in the repository root for persistent, shell-agnostic configuration
- **Absolute paths** are used as-is; **relative paths** resolve against the repository location
- **All Career-Ops commands** automatically use the configured directory for reading and writing data

## Frequently Asked Questions

### Can I use both environment variables simultaneously?

Yes, but `CAREER_OPS_ROOT` takes precedence over `CAREER_OPS_DATA_DIR`. If you set both, Career-Ops uses the value from `CAREER_OPS_ROOT` and ignores the secondary variable. The marker file is only consulted when neither variable is present.

### Does Career-Ops expand shell variables like `$HOME` in paths?

No. The resolver reads environment variables directly using `process.env` and does not perform shell expansion. Use absolute paths or paths relative to the repository root rather than shell variables like `$HOME/data`.

### What happens if the external directory does not exist?

Career-Ops attempts to create necessary subdirectories within the configured path. However, the parent directory must exist and be writable by the user running the command. The `path-resolver.mjs` logic resolves the path but does not validate existence until specific operations attempt file I/O.

### Can different repositories point to different data directories?

Yes. Each Career-Ops instance resolves paths independently based on its own environment or marker file. You can maintain multiple career data repositories by setting different `CAREER_OPS_ROOT` values before invoking commands in each directory, or by placing unique `.career-ops-data` files in separate repository clones.