# Opening files and addresses

> The command line flags HTML Clay accepts, and the settings, log, and version history files it keeps on disk.

Source: https://htmlclay.com/docs/opening-files/

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`.

```json
{
  "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.