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

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:

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

Use a relative path resolved against the repository:

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

Create the marker file for persistent configuration:

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

Configuration Precedence and Documentation

The resolution order is explicitly defined in 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 file formally specifies these variables as part of the official configuration interface, while the 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.

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