# Where Are Modly Configuration Files Located?

> Locate Modly configuration files easily. Find settings.json for Electron apps and CLI tools on Windows, Linux, and macOS for seamless Modly management.

- Repository: [lightningpixel/modly](https://github.com/lightningpixel/modly)
- Tags: how-to-guide
- Published: 2026-08-19

---

**Modly stores user settings in a JSON file named [`settings.json`](https://github.com/lightningpixel/modly/blob/main/settings.json), with the location determined by whether you are running the Electron desktop app (`<userData>/settings.json`) or the CLI tool (`%APPDATA%\Modly\settings.json` on Windows or `~/.config/Modly/settings.json` on Linux/macOS).**

Modly is an open-source application distributed across desktop and command-line interfaces. According to the `lightningpixel/modly` source code, the repository maintains separate configuration resolution logic for its Electron frontend and Python-based CLI tool, ensuring settings persist correctly across different runtime environments.

## Electron Desktop Application Configuration

When running Modly as a desktop application, the configuration file resides in Electron's **user data directory**.

The path is constructed using `app.getPath('userData')` and resolves to a platform-specific location (for example, `%APPDATA%\Modly` on Windows or `~/Library/Application Support/Modly` on macOS). The actual filename is [`settings.json`](https://github.com/lightningpixel/modly/blob/main/settings.json).

In [`electron/main/settings-store.ts`](https://github.com/lightningpixel/modly/blob/main/electron/main/settings-store.ts), the implementation reads and writes to this location directly. When the file does not exist, the `getSettings` function falls back to sensible defaults, creating directories like `<userData>/models` and `<userData>/workspace` automatically.

## CLI Tool Configuration Locations

For the `modly` command-line interface, the configuration resolution follows a different pattern implemented in [`tools/modly-cli/agent.py`](https://github.com/lightningpixel/modly/blob/main/tools/modly-cli/agent.py) within the `_load_modly_settings` function.

The CLI searches through the following candidate locations in order:

1. **Windows**: `%APPDATA%\Modly\settings.json`
2. **Linux/macOS**: `~/.config/Modly/settings.json`

The Python implementation iterates through these paths and returns the first existing file found. If no configuration file exists at any candidate location, the CLI applies default values programmatically.

## Configuration File Structure

The [`settings.json`](https://github.com/lightningpixel/modly/blob/main/settings.json) file contains keys that define directory paths and authentication tokens:

```json
{
  "modelsDir": "...",
  "workspaceDir": "...",
  "workflowsDir": "...",
  "extensionsDir": "...",
  "dependenciesDir": "...",
  "hfToken": "optional-HuggingFace-token"
}

```

**Key directories** include `modelsDir` for model storage, `workspaceDir` for user projects, and `extensionsDir` for plugin management. The `hfToken` field optionally stores HuggingFace authentication credentials.

## Accessing Settings Programmatically

### Electron Renderer Process

The frontend accesses settings through an IPC layer defined in [`electron/preload/electron-api.ts`](https://github.com/lightningpixel/modly/blob/main/electron/preload/electron-api.ts). The preload script exposes two channels: `settings:get` for reading and `settings:set` for updating values.

**Reading settings in a React component:**

```typescript
import { useEffect, useState } from 'react';

export function useModlySettings() {
  const [settings, setSettings] = useState<{
    modelsDir: string;
    workspaceDir: string;
    workflowsDir: string;
    extensionsDir: string;
  } | null>(null);

  useEffect(() => {
    window.electron.settings.get().then(setSettings);
  }, []);

  return settings;
}

```

**Updating configuration values:**

```typescript
await window.electron.settings.set({ workspaceDir: '/new/workspace/path' });

```

### CLI Implementation

For Python-based tooling, load the configuration by checking the candidate paths manually:

```python
import json
import os
from pathlib import Path

def load_modly_settings() -> dict:
    candidates = [
        Path(os.getenv('APPDATA', '')) / 'Modly' / 'settings.json',
        Path.home() / '.config' / 'Modly' / 'settings.json',
    ]
    for p in candidates:
        if p.is_file():
            return json.loads(p.read_text())
    return {}  # Defaults applied downstream

```

## Backend API Integration

The [`api/routers/settings.py`](https://github.com/lightningpixel/modly/blob/main/api/routers/settings.py) file implements a FastAPI router that forwards HTTP requests to the same settings backend used by the Electron main process. This ensures consistency between direct API calls and desktop application operations, with both interfaces ultimately reading from the [`settings.json`](https://github.com/lightningpixel/modly/blob/main/settings.json) file determined by the runtime context.

## Summary

- **Electron App**: Stores [`settings.json`](https://github.com/lightningpixel/modly/blob/main/settings.json) in the Electron user data directory (`app.getPath('userData')`), implemented in [`electron/main/settings-store.ts`](https://github.com/lightningpixel/modly/blob/main/electron/main/settings-store.ts).
- **CLI Tool**: Searches `%APPDATA%\Modly\settings.json` (Windows) or `~/.config/Modly/settings.json` (Linux/macOS) via the `_load_modly_settings` function in [`tools/modly-cli/agent.py`](https://github.com/lightningpixel/modly/blob/main/tools/modly-cli/agent.py).
- **Structure**: JSON file containing directory paths (`modelsDir`, `workspaceDir`, etc.) and optional tokens.
- **Access**: Frontend uses `window.electron.settings` IPC channels (`settings:get`, `settings:set`); CLI uses direct filesystem access with fallback defaults.

## Frequently Asked Questions

### What is the default location for Modly settings on Windows?

On Windows, the Electron desktop app stores [`settings.json`](https://github.com/lightningpixel/modly/blob/main/settings.json) in `%APPDATA%\Modly` (specifically within Electron's user data path), while the CLI tool specifically looks for `%APPDATA%\Modly\settings.json` as its first candidate location. Both resolve to the Roaming AppData folder under the user's profile.

### How does Modly handle missing configuration files?

When [`settings.json`](https://github.com/lightningpixel/modly/blob/main/settings.json) does not exist at the expected path, Modly generates default values rather than throwing errors. The Electron implementation creates default directories (such as `<userData>/models`) on first run, while the CLI applies hardcoded fallback values if the `_load_modly_settings` function returns an empty dictionary.

### Can I manually edit the settings.json file?

Yes. Since [`settings.json`](https://github.com/lightningpixel/modly/blob/main/settings.json) is a standard JSON file, you can edit it with any text editor when Modly is not running. Changes take effect on the next application start. Be sure to maintain valid JSON syntax, particularly for path strings that require escaped backslashes on Windows.

### Why does Modly use different config paths for CLI and Desktop?

The Electron framework manages its own user data directory through `app.getPath('userData')`, which follows OS-specific conventions for GUI applications. The CLI tool follows XDG Base Directory specifications on Linux/macOS and Windows environment variables (`APPDATA`) to align with command-line user expectations, ensuring compatibility with standard terminal workflows and remote server deployments where Electron is not present.