- HTML Clay
- Docs
- Host reference
- Configuration
Configuration
Reference for every setting in config.json, every command-line flag and subcommand, and every environment variable HTML Clay reads.
HTML Clay stores its settings, logs, and version 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 of edited documents. |
updates/ | Staged release binaries and seen.json version history for 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. |
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. 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, capped at 32 entries. |
helperDecisions | [] | Per-document allow decisions for document programs, capped at 512 entries. |
aiEdit | { "enabled": true, "default": "" } | Configures 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. 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. 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 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. |
COMSPEC | cmd.exe | Command interpreter used on Windows when launching helper commands and opening URLs. |