# Configuration

> Reference for every setting in config.json, every command-line flag and subcommand, and every environment variable HTML Clay reads.

Source: https://htmlclay.com/docs/configuration/

HTML Clay stores its settings, logs, and [version backups](https://htmlclay.com/docs/guide/backups/) in `<UserConfigDir>/htmlclay`. On first launch, if an older `~/.htmlclay` folder exists, HTML Clay migrates it automatically.

There is no command-line flag or environment variable to override the configuration directory or choose an arbitrary port. To change the port manually, edit `port` in `config.json` while HTML Clay is not running.

## Files in the configuration directory

| Path | Purpose |
|---|---|
| `config.json` | Main configuration file, written atomically with file mode `0600`. |
| `htmlclay.log` | Application log file. |
| `versions/` | Saved [backups](https://htmlclay.com/docs/guide/backups/) of edited documents. |
| `updates/` | Staged release binaries and `seen.json` version history for [updates](https://htmlclay.com/docs/guide/updates/). |
| `update-handoff.json` | Temporary state file that passes open documents, save tokens, and permissions across an update restart. |

If `config.json` is corrupt when HTML Clay starts, HTML Clay renames the file to `config.json.corrupt-<unix-time>`, logs a notice to standard error, and starts with default settings.

## Settings in `config.json`

| Key | Default | Description |
|---|---|---|
| `startOnLogin` | `false` | Starts HTML Clay automatically when you sign in. Toggled by **Start on Login** in the [tray menu](https://htmlclay.com/docs/tray/). |
| `port` | `0` | The single loopback port HTML Clay serves every folder on (`127.0.0.1` and `::1`). When `0`, HTML Clay picks the first free port from `1212`, `4545`, `9797`, `3434`, `1111`, or a random port between `10000` and `32767` (excluding `10080`), then saves it here. |
| `siteSlugs` | `{}` | Maps each folder key to its permanent `.localhost` hostname label (`htmlclay`, `htmlclay1`, `htmlclay2`, and so on). Assigned once per folder so bookmarks survive restarts. |
| `retiredSlugs` | `[]` | Hostname labels that have been retired. They are never reissued and serve the recovery page. |
| `nextSiteNumber` | `1` | Counter for assigning the next folder hostname label (`1` is `htmlclay`, `2` is `htmlclay1`, and so on). |
| `sitePorts` | `{}` | Legacy per-folder port map kept only to `302`-redirect old bookmarks to the folder's `.localhost` address. |
| `workspaceFolders` | `[]` | List of [trusted folders](https://htmlclay.com/docs/guide/trusted-folders/). Each entry is `{ "path": "...", "identity": "..." }`. |
| `trustedFolders` | `[]` | Legacy read-only folder list from v1.2.0, promoted once into `workspaceFolders` and cleared. |
| `helperPrograms` | `[]` | Registered [document programs](https://htmlclay.com/docs/programs/), capped at 32 entries. |
| `helperDecisions` | `[]` | Per-document allow decisions for document programs, capped at 512 entries. |
| `aiEdit` | `{ "enabled": true, "default": "" }` | Configures [AI editing](https://htmlclay.com/docs/guide/ai-editing/). Missing means enabled. An empty `default` uses Claude Code (`claude`). `engines` maps custom engine names to `argv` arrays with `{prompt}` substitution. |
| `profile` | `null` | Author profile `{ "enabled": false, "id": "...", "name": "..." }` used with ClayJS's [`people` plugin](https://clayjs.com/docs/plugins/people/). Absent or `null` means off. Names are capped at 120 characters and email addresses are refused. |
| `updates` | `""` | Set to `"off"` to turn off automatic [self-updates](https://htmlclay.com/docs/guide/updates/). Any other value or omitting the key leaves self-update on. |

## Command-line flags

The `htmlclay` binary accepts three top-level flags:

| Flag | Default | Description |
|---|---|---|
| `-no-tray` | `false` | Run without the system tray and shut down on OS signals. Disables self-update. |
| `-unregister` | `false` | Remove the **Start on Login** entry and every file association HTML Clay registered, then exit. Leaves your documents, trusted folders, and backups untouched. |
| `-finish-update` | `false` | Internal flag used by the updater to complete an update started by the previous version. |

### CLI subcommands and flags

HTML Clay also provides `update-now` (on macOS) and the [`htmlclay wire`](https://htmlclay.com/docs/wire-cli/) subcommands:

| Command and flags | Default | Description |
|---|---|---|
| `htmlclay update-now --version <X.Y.Z>` | required | macOS only. Asks the running HTML Clay app to install update `<X.Y.Z>` immediately (exit codes `0` to `6`). |
| `htmlclay wire serve <file> [--protocol=jsonl] -- <cmd> [args...]` | plain text | Attaches `<cmd>` as the wire handler for `<file>`. With `--protocol=jsonl`, stdout lines are parsed as JSONL records instead of progress text. |
| `htmlclay wire listen <file> [--handler]` | `--handler=false` | Streams wire events for `<file>`. Pass `--handler` to connect in the handler role. |
| `htmlclay wire send <file> --type <type>` | required | Sends a wire message to `<file>`. |
| `htmlclay wire where <file>` | none | Prints the `.localhost` folder address currently serving `<file>`. |
| `--origin <url>` | inferred | Optional flag on every `htmlclay wire` subcommand to specify the folder origin URL explicitly. |
| `--port <n>` | from `config.json` | Optional flag on every `htmlclay wire` subcommand to specify the loopback port explicitly. |

## Environment variables

| Variable | Default | Description |
|---|---|---|
| `HTMLCLAY_UPDATE_FEED` | `https://download.htmlclay.com/update/stable.json` | Overrides the signed update feed URL on Windows and Linux. |
| `HTMLCLAY_TAILWIND_BIN` | bundled binary | Path to an external Tailwind compiler. Used only in development builds without a bundled binary; ignored by release builds. |
| `XDG_CONFIG_HOME` | `~/.config` | Base configuration folder on Linux used to place the autostart `.desktop` entry (`$XDG_CONFIG_HOME/autostart`). |
| `SHELL` | system login shell | Login shell executed on macOS and Linux to read `PATH` before starting [document programs](https://htmlclay.com/docs/programs/). |
| `COMSPEC` | `cmd.exe` | Command interpreter used on Windows when launching helper commands and opening URLs. |