Opening files and addresses

The executable takes two flags and one subcommand, opens at most one file per launch, and keeps its settings, log, and version history in your operating system’s config directory.

The binary’s own flags#

The executable takes exactly two flags plus one subcommand. Both -name and --name spellings work.

htmlclay [--no-tray] [--unregister] [file]
htmlclay wire <subcommand> ...

• --no-tray runs without the system tray and shuts down on SIGINT or SIGTERM.
• --unregister removes the file associations and the Start on Login entry, then exits. It runs before the single-instance lock, so it works whether or not the app is running. It does not touch config.json, the trusted-folder list, or saved versions.
• A trailing path argument opens that file. Only the first is used. If another instance already holds the lock, the path is forwarded to it and this process exits 0.

Files on disk#

Configuration lives at <os-config-dir>/htmlclay/config.json, where <os-config-dir> is ~/Library/Application Support on macOS, ~/.config on Linux, and %APPDATA% on Windows. The log is <os-config-dir>/htmlclay/htmlclay.log, rotated at 10 MB. Versions are in <os-config-dir>/htmlclay/versions.

{
  "startOnLogin": false,
  "port": 1212,
  "siteSlugs": {
    "/Users/you/projects/notes": "htmlclay1"
  },
  "retiredSlugs": [
    "htmlclay"
  ],
  "nextSiteNumber": 3,
  "sitePorts": {
    "/Users/you/projects/notes": 54321
  },
  "workspaceFolders": [
    { "path": "/Users/you/projects/notes", "identity": "16777229:224754543" }
  ]
}

port is the one port every folder is served on, chosen on the first launch and bound again at every startup. siteSlugs remembers the hostname each folder answers at, keyed by its anchor folder, and is what the htmlclay wire CLI reads to find an origin; a label is chosen once and never changes. retiredSlugs are labels that were once issued and then given up, which are never issued again, so no folder can inherit another’s browser storage. Labels are htmlclay, then htmlclay1, htmlclay2, and so on, in the order folders are first served, and nextSiteNumber is the next one; a number is never reused.

sitePorts is the legacy record from the per-folder-port model, kept only so an old 127.0.0.1:<port> bookmark redirects to the folder’s hostname while that port is free; nothing new is ever written to it. The trusted-folder list keeps the on-disk key workspaceFolders from the version that introduced it; renaming the key would make older configs fail to parse, and the corrupt-config path would then reset every other setting. identity is the folder’s fingerprint at the moment you trusted it. An entry recorded before Windows could fingerprint a directory has no identity; it keeps working and gains one on the next launch.

A single instance is enforced with a Unix socket, or TCP on Windows. Additional launches forward their file paths to the running instance and exit.

Every folder is served on that one loopback port, at an address like http://htmlclay.localhost:1212/<path>, where htmlclay is the folder’s own label.