# How to Configure the Default Mode for Ponytail: Environment Variables and Config Files

> Configure Ponytail's default mode using environment variables or config files. Learn how to set PONYTAIL_DEFAULT_MODE or defaultMode in config.json for flexible operation.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: how-to-guide
- Published: 2026-08-29

---

**You can configure Ponytail’s default operating mode by setting the `PONYTAIL_DEFAULT_MODE` environment variable (highest priority), defining a `defaultMode` field in your platform-specific [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json), or relying on the built-in fallback value of `full`.**

Ponytail determines its startup behavior through a hierarchical resolution system implemented in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js). According to the DietrichGebert/ponytail source code, the tool resolves the default mode through three distinct priority levels, accepting only the runtime modes (`off`, `lite`, `full`, `ultra`) while explicitly excluding the session-only `review` mode.

## The Three-Level Resolution Hierarchy

Ponytail’s `getDefaultMode()` function implements a cascading lookup strategy. The first valid source found determines the starting mode for any new Ponytail process.

### 1. Environment Variable (Highest Priority)

When the `PONYTAIL_DEFAULT_MODE` environment variable is defined, its value overrides all other configuration sources. The variable is read at lines 78–84 in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js), where the code checks for the presence of the variable and validates that it contains an allowed runtime mode.

### 2. User Configuration File

If the environment variable is absent, Ponytail queries a JSON configuration file. The helper function `getConfigPath()` (lines 67–70) resolves the platform-specific location:

- **Linux/macOS**: `~/.config/ponytail/config.json` (or `$XDG_CONFIG_HOME/ponytail/config.json` if `XDG_CONFIG_HOME` is set)
- **Windows**: `%APPDATA%\ponytail\config.json`

The `getDefaultMode()` function then reads the `defaultMode` property from this file at lines 86–94.

### 3. Built-in Fallback

If neither the environment variable nor a valid config entry exists, Ponytail falls back to the constant `DEFAULT_MODE = 'full'` defined at line 16 in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js).

## Setting the Default Mode via Environment Variable

Configuring via environment variable takes effect immediately for new processes without modifying files. Use the appropriate syntax for your shell:

```bash

# Bash/Zsh

export PONYTAIL_DEFAULT_MODE=lite

# Windows CMD

set PONYTAIL_DEFAULT_MODE=lite

# PowerShell

$env:PONYTAIL_DEFAULT_MODE = "lite"

```

The validation logic at line 82 ensures that only `off`, `lite`, `full`, or `ultra` are accepted; invalid values trigger a fallback to the next resolution level.

## Configuring the Default Mode via Config File

For persistent configuration across system restarts, create or edit the [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) file. First, ensure the directory exists:

```bash
mkdir -p ~/.config/ponytail

```

Then create the file with your desired default:

```bash
cat > ~/.config/ponytail/config.json <<EOF
{
  "defaultMode": "ultra",
  "quietStartup": true,
  "hideStatus": false
}
EOF

```

Alternatively, use the programmatic API `writeDefaultMode(mode)` exported from [`ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-config.js). This method calls `normalizeMode()` (lines 20–24) to validate inputs before persisting them to disk, ensuring only valid runtime modes are written.

## Programmatic Configuration Examples

When building tools on top of Ponytail, you can query or modify the default mode directly from Node.js.

### Querying the Current Effective Default

```javascript
const cfg = require('./hooks/ponytail-config');
console.log('Effective default mode:', cfg.getDefaultMode());
// Output: "full" (or whatever is resolved from env/config/fallback)

```

### Changing the Default Mode Programmatically

```javascript
const cfg = require('./hooks/ponytail-config');

// Attempts to write to the user config file
if (cfg.writeDefaultMode('lite')) {
  console.log('Default mode updated to lite');
} else {
  console.error('Invalid mode; must be off|lite|full|ultra');
}

```

### Using Environment Variables in Scripts

```bash
#!/usr/bin/env bash
export PONYTAIL_DEFAULT_MODE=off
node -e "console.log(require('./hooks/ponytail-config').getDefaultMode())"

# Prints: "off"

```

## Valid Mode Constraints

The `normalizeMode()` function enforces strict validation: only **runtime-level modes** (`off`, `lite`, `full`, `ultra`) are eligible as defaults. The `review` mode is deliberately excluded at line 82 because it is designed for session-only usage within [`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js). Attempting to set an invalid mode via any configuration method results in the validator rejecting the value and triggering the fallback mechanism.

## Summary

- **Environment Variable**: Set `PONYTAIL_DEFAULT_MODE` to `off`, `lite`, `full`, or `ultra` for immediate, process-level configuration.
- **Config File**: Create [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) in your platform-specific config directory (`~/.config/ponytail/` on Linux/macOS, `%APPDATA%\ponytail\` on Windows) for persistent settings.
- **Fallback**: The constant `DEFAULT_MODE = 'full'` at line 16 ensures the application never starts without a valid mode.
- **Validation**: Both `normalizeMode()` (lines 20–24) and the environment variable checker (line 82) exclude the `review` mode and invalid strings.

## Frequently Asked Questions

### What happens if I don’t configure a default mode?

If you do not set the `PONYTAIL_DEFAULT_MODE` environment variable and no [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) file exists (or it lacks a `defaultMode` entry), Ponytail uses the built-in constant `DEFAULT_MODE = 'full'` defined at line 16 in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js). This ensures the application always starts with a predictable baseline behavior.

### Can I set "review" as the default mode?

No. The validation logic at line 82 in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) explicitly filters out the `review` mode when resolving defaults. Only the runtime modes (`off`, `lite`, `full`, `ultra`) are permitted; `review` is restricted to session-level usage within [`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js).

### Where is the configuration file stored on different operating systems?

On Linux and macOS, Ponytail checks `~/.config/ponytail/config.json` (or `$XDG_CONFIG_HOME/ponytail/config.json` if the XDG variable is defined). On Windows, the path resolves to `%APPDATA%\ponytail\config.json`. The `getConfigPath()` helper at lines 67–70 handles the platform detection automatically.

### How do I programmatically change the default mode from my Node.js application?

Import [`ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-config.js) and call `writeDefaultMode(mode)`, passing one of the valid runtime strings. This function validates the input through `normalizeMode()` (lines 20–24) and writes the change to the user config file if valid, returning a boolean indicating success or failure.