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

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 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, 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, 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 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, 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, 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.

# 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:

# 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:

# 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:

# 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 – Provides an overview of CAREER_OPS_ROOT and CAREER_OPS_TRACKER overrides.
• README.md – Contains quick-start instructions mentioning both primary variables.
• DATA_CONTRACT.md – Defines the formal data contract for variable usage and path resolution.
• docs/SCRIPTS.md – Documents script-level implementations of all environment variables.
• 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.
• 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 and implemented in 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). This overrides only the tracker file location, leaving other data files like 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, data/pipeline.md, and other default paths occur within the repository structure itself.

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