Configure Default Working Directory

Commander supports flexible configuration of its working directory through environment variables and command-line parameters, including full XDG Base Directory Specification compliance.

Overview

By default, Commander stores its configuration and logging files in ~/.keeper. You can customize this location using environment variables for system-wide configuration or command-line parameters for session-specific overrides.

Supported Methods

Command-Line Parameter

Use --data-dir to override the working directory for a specific session.

keeper shell --data-dir /tmp/keeper-session
# Uses: /tmp/keeper-session/.keeper/

Environment Variables

KEEPER_DATA_HOME

Set a custom data directory for Commander across all sessions.

export KEEPER_DATA_HOME="/opt/keeper-data"
keeper shell
# Uses: /opt/keeper-data/.keeper/

XDG_DATA_HOME (XDG Compliance)

Follow the XDG Base Directory Specification for organized user data.

export XDG_DATA_HOME="$HOME/.local/share"
keeper shell
# Uses: $HOME/.local/share/.keeper/

Precedence Order

Commander determines the working directory using the following precedence (highest to lowest):

1. CLI Parameter - --data-dir flag
2. KEEPER_DATA_HOME - Environment variable
3. XDG_DATA_HOME - XDG Base Directory Specification
4. Default - ~/.keeper (legacy compatibility)

Smart Path Handling

Commander automatically appends .keeper to paths when needed:

Auto-Append Behavior

• Input: /Users/john → Output: /Users/john/.keeper
• Input: /Users/john/.keeper → Output: /Users/john/.keeper (unchanged)

This applies to both CLI parameters and the KEEPER_DATA_HOME environment variable.

XDG Compliance

When using XDG_DATA_HOME, Commander always appends .keeper:

• XDG_DATA_HOME=/opt/data → Uses /opt/data/.keeper

Usage Examples

Basic Environment Variable Setup

# Set custom data directory
export KEEPER_DATA_HOME="/opt/keeper"
keeper shell
# config.json stored in: /opt/keeper/.keeper/

XDG Base Directory Compliance

# Follow XDG specification
export XDG_DATA_HOME="$HOME/.local/share"
keeper shell
# config.json stored in: $HOME/.local/share/.keeper/

Session-Specific Override

# Use specific directory for testing
keeper shell --data-dir /tmp/test-session
# config.json stored in: /tmp/test-session/.keeper/

Corporate Environment

# Company-wide configuration
export XDG_DATA_HOME="/mnt/userdata/$USER"
keeper shell
# config.json stored in: /mnt/userdata/john/.keeper/

Command-Line Reference

Global Options

keeper [command] --data-dir <path>

Parameters:

• --data-dir <path> - Directory to use for Commander data (overrides environment variables)

Examples:

# Use custom directory
keeper shell --data-dir /custom/path

Environment Variable Reference

Variable	Description	Example
KEEPER_DATA_HOME	Custom Commander data directory	/opt/keeper
XDG_DATA_HOME	XDG Base Directory for user data	$HOME/.local/share

Troubleshooting

Common Issues

Permission Errors

Ensure the specified directory is writable:

# Check permissions
ls -la /path/to/parent/directory

# Fix permissions if needed
chmod 755 /path/to/parent/directory

Path Not Found

Commander creates directories automatically, but parent directories must exist:

# Create parent directory
mkdir -p /path/to/parent
keeper --data-dir /path/to/parent/keeper shell

Environment Variable Not Working

Verify the environment variable is set correctly:

# Check current value
echo $KEEPER_DATA_HOME
echo $XDG_DATA_HOME

Compatibility Notes

• Backward Compatible: Existing ~/.keeper installations continue working
• Forward Compatible: New environment variables provide enhanced flexibility
• Cross-Platform: Works on macOS, Linux, and Windows
• XDG Compliant: Follows Unix standards for data directory organization