# Configure Default Working Directory

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

```bash
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.

```bash
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.

```bash
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

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

#### XDG Base Directory Compliance

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

#### Session-Specific Override

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

#### Corporate Environment

```bash
# 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

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

**Parameters:**

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

**Examples:**

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

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

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

```bash
# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/keeperpam/commander-cli/commander-installation-setup/configuration/configure-default-working-directory.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.