Documentation

Everything beyond "click record": the developer console, config scripts, plugins, and the hom plugin manager.

1. The developer console

HomRec has a built-in console for scripting and diagnostics — it's the same idea as a game's dev console (think Source/Quake), not a general shell. Open it from the app (Help/Debug menu), type a command, press Enter.

Commands share one line format:

command [arguments]

A few conventions apply everywhere:

• Flags look like --name or --name=value.
• Commands chain with && via batch.
• Anything not matching a built-in is handed to loaded plugins in case one of them registered that command name (see Plugins) — otherwise you get Unknown command: ....

2. Built-in commands

Diagnostics

Command	What it does
version	Prints HomRec v2.0 (developer console).
ver	Prints the bare version number (2.0) — handy in scripts that need just the number.
ping	Replies pong — quick check that the console is alive.
info	Prints CPU core count, RAM total/used, whether FFmpeg was found, and which encoder got picked (hardware GPU encoder vs. software libx264 fallback). The encoder line is the fastest way to answer "why is recording eating my CPU."
status	Shows idle, or RECORDING/PAUSED with elapsed time and current frame count.
log	See below.

The log command

Form	Effect
log <message>	Appends [console] <message> to homrec.log.
log open	Opens homrec.log in your default text editor.
log clear	Truncates (empties) homrec.log — the file itself stays, only its contents are wiped.

Console utilities

Command	What it does
echo [--ok|--warn|--err] <text>	Prints text, optionally styled as success/warning/error.
clear	Clears the console output pane (not the same as log clear).
history	Lists every command run this session, numbered.
env	No args: lists session env vars. env NAME: prints its value. env NAME=value: sets it. Vars live only for the current session.
alias	No args: lists aliases. alias name=target: defines one (names are lower-cased).
ls [--aliases] [--env]	Lists aliases and/or env vars — the native equivalent of "list the registry" from the old command language, which doesn't otherwise exist in this port.
clip --copy "text" / --paste / --clear	Reads/writes the Windows clipboard.
hide	Hides the main window; restore it from the tray icon.
hrc save [path] / hrc load [path]	Saves or loads HomRec's settings to/from a .hrc file (default: homrec_config.hrc next to the exe). Some fields need a restart to take effect after loading.

Scripting: repeat and batch

Command	What it does
repeat --count=N <command>	Runs a command N times in a row (capped at 1000).
batch cmd1 && cmd2 && ... [-x | --stop-on-error]	Runs several commands in sequence. -x is accepted but only loosely enforced right now — most commands print their own error without yet reporting pass/fail back to batch.

Removal commands

Command	What it does
rm --system@homrec.files --permission=core --type={recordings,plugins,logs,cache}	Deletes the listed data folders (any combination). E.g. --type={logs,cache} clears just those two.
rm @homrec [-q]	Uninstalls HomRec entirely once the app closes (confirmation prompt unless -q/-y is passed).

3. Config scripts

Drop a .cfg file into the cfg/ folder next to the exe (created automatically) and HomRec will run it line-by-line through the console, one command per line. Blank lines are skipped, and both // and # work as comment markers so you can use whichever convention you're used to.

// cfg/autoexec.cfg — runs automatically on startup
echo --ok HomRec ready
alias qr=hrc load quickrec.hrc
env THEME=dark

.cfg files are read leniently (UTF-8 first, falling back to the system ANSI codepage), since they're meant to be hand-edited in whatever text editor you've got on Windows.

4. Console security

Three independent toggles gate different parts of the console. Each reports its state with no argument, or is set with 0/off/false to disable, anything else to enable:

Command	Guards
sec [0|1]	The master fuse. Must be 0 before either rm command will run.
secui [0|1]	UI protection.
secp [0|1]	Plugin version-check / RAM watchdog.

Example: sec 0 then rm --system@homrec.files --permission=core --type={cache}.

5. Plugins (Lua)

Plugins are Lua scripts loaded from plugins/, either as a loose folder or a packaged .hrp archive. Each plugin needs a small manifest:

{
    "id": "my_plugin",
    "name": "My Plugin",
    "version": "1.0.0",
    "entry": "entry.lua"
}

and an entry script with an on_load() function HomRec calls when it loads the plugin:

function on_load()
    homrec.register_command("hello", "Says hi", function(args)
        homrec.print("Hello from my_plugin!")
    end)
end

The homrec.* API

Function	Purpose
homrec.register_command(name, description, fn)	Adds a console command that runs your Lua function.
homrec.register_input_overlay(category, label, json_path, png_path)	Registers an input-overlay preset (keyboard/mouse/gamepad).
homrec.print(text) / homrec.log(message, level?) / homrec.log_to(filename, message)	Console output and logging, including to a custom file under your plugin's own log.
homrec.show_toast(message, color?, duration_ms?)	Shows a small non-blocking popup.
homrec.store_get/store_set	Persistent per-plugin key/value storage.
homrec.settings_get/settings_set	Reads/writes HomRec's own settings flags.
homrec.get_colors()	Returns the active UI theme's colors.
homrec.get_ffmpeg()	Returns the path to the FFmpeg binary HomRec is using.
homrec.plugin_info()	Returns your own plugin's {id, name, version, author}.
homrec.http_get(url) / homrec.http_post(url, body, content_type?)	Basic HTTPS requests.
homrec.emit(...)	Emits an event other plugins can react to.

Console commands a plugin registers are dispatched exactly like built-ins — if you type a name the console doesn't recognize natively, it's handed to plugins before giving up.

6. hom — the plugin package manager

hom.exe is a separate, tiny executable (no wxWidgets/Lua dependency) you keep next to hr.exe for installing plugins the same way apt or pacman installs packages — just aimed at .hrp plugin files instead of system packages. Plugins are served straight out of the HomRec GitHub repo's Hom/ folder over plain HTTPS (raw.githubusercontent.com) — no server, no API, no database, no login.

Commands

Command	What it does
hom --version	Prints the installed hom version.
hom update [-f|--force]	Checks the repo for a newer hom.exe and, if found, downloads it and swaps it in for the one you're running. -f/--force re-downloads and reinstalls even if you're already up to date. This updates hom itself, not a plugin index — hom has no local package index to go stale, since search/show/install always ask the repo live. Still fine to run out of habit; it's cheap.
hom ping	Checks connectivity to the plugin repo and reports round-trip time.
hom install <name> [-y] [-f|--force]	Downloads Hom/plugins/<name>.hrp into ./plugins/<name>.hrp. HomRec's own plugin loader extracts and loads it the next time it starts — hom's job stops at "the file is on disk." If the download would grow disk usage by more than ~1 MB, asks for confirmation first unless -y/-f is given.
hom upgrade [-y] [-f|--force]	Re-downloads every plugin you already have installed to whatever's currently in the repo, without removing anything.
hom full-upgrade [-y] [-f|--force]	Currently identical to hom upgrade — see the note below.
hom remove <name> -r	Removes a plugin's code, but keeps its saved settings (see "remove vs. purge" below). -r is required to confirm.
hom purge <name> -r	Removes a plugin's code and its saved settings — nothing is left behind. -r is required to confirm.
hom autoremove	Currently always a no-op — see the note below.
hom search <query>	Matches query against every plugin's name and description in the repo's index. Tried as a case-insensitive regex first, falling back to a plain substring match if query isn't valid regex syntax.
hom show <name>	Prints what the repo knows about a plugin — version, author, description, package size — plus whether it's installed here and at what local version.
hom list --installed	Lists every plugin found under ./plugins here, with its locally-known version.
hom list --upgradable	Same scan, but only prints plugins where the repo has a newer version than what's installed locally.

> hom search overlay
input-overlay (1.0.0) - Keyboard / mouse / gamepad input overlay presets (WASD, QWERTY, mouse, gamepad).

> hom show input-overlay
Name:        input-overlay
Version:     1.0.0
Author:      HomRec
Description: Keyboard / mouse / gamepad input overlay presets (WASD, QWERTY, mouse, gamepad).
Package:     Hom/plugins/input-overlay.hrp
Size:        540.0 KB
Installed:   no

> hom install input-overlay
Fetching plugin 'input-overlay'...
Installed 'input-overlay' -> plugins\input-overlay.hrp (552854 bytes)
Restart HomRec (or reload plugins) to pick it up.

> hom list --installed
input-overlay (version unknown)

"Version unknown" above is expected right after a fresh install — a plugin's known version comes from the plugin.json HomRec's own loader extracts, so until HomRec has actually started up once (or you run hom upgrade, which re-fetches and re-checks it), hom has nothing local to compare against.

remove vs. purge

Plugins can save their own persistent settings (a small .store file alongside the plugin's code — see homrec.store_get/store_set in the plugins API). hom remove deletes a plugin's code but leaves that file behind, the same way apt remove leaves /etc config in place — reinstalling the plugin later picks its old settings back up. hom purge deletes everything, including that saved data.

> hom remove input-overlay -r
Removed plugins\input-overlay.hrp
hom: plugin removed. Its saved settings (if any) were kept -- use 'hom purge input-overlay -r' to delete those too.

> hom purge input-overlay -r
Removed plugins\.installed\input-overlay

Every plugin name passed to install/remove/purge/show is rejected outright if it contains .., a path separator, or a drive letter — none of them can ever resolve to anything outside .\plugins\, no matter what's typed.

From the console

You don't need to leave HomRec to use hom — the built-in hom command (see Built-in commands) forwards straight to hom.exe as a child process, working directory forced to HomRec's own folder, so it behaves identically to running it from PowerShell/cmd. The destructive subcommands — update, remove/uninstall, purge, and autoremove — additionally need the inwid confirmation prefix from inside the console:

> hom remove input-overlay -r
Blocked: this needs the 'inwid' prefix, e.g. 'inwid hom remove input-overlay -r'

> inwid hom remove input-overlay -r
Removed plugins\input-overlay.hrp
hom: plugin removed. Its saved settings (if any) were kept -- use 'hom purge input-overlay -r' to delete those too.

install, upgrade, full-upgrade, search, show, and list don't need inwid — none of them delete anything you didn't just ask to add or refresh.

Where plugins come from

Everything hom reads comes from this repo's own Hom/ folder:

Hom/
  version.txt          current hom version, e.g. "0.4" -- checked by `hom update`
  hom.exe              latest prebuilt hom.exe -- downloaded by `hom update`
  plugins/
    index.json         listing of available plugins -- read by `hom search`/`hom show`/
                        `hom list --upgradable`
    <name>.hrp          a plugin package -- `hom install <name>` downloads this

index.json is the one file worth knowing about if you're publishing a plugin: hom install <name> itself doesn't need it (it just requests plugins/<name>.hrp directly), but search, show, and list --upgradable only know about what's listed there, including each plugin's version field — so publishing a plugin update without bumping its version in index.json means hom list --upgradable won't notice there's anything new.

7. FAQ

Does rm ask for confirmation?

rm --system@homrec.files does not (beyond needing sec 0 first). rm @homrec pops a Yes/No dialog unless you pass -q/-y.

Does hom remove/hom purge ask for confirmation?

Not with a pop-up — both refuse to run at all unless you pass -r (e.g. hom remove input-overlay -r), which serves as the "yes, actually delete it" confirmation. From the console, they additionally need the inwid prefix.

Where do plugin commands show up if I don't remember the plugin's name?

There's no help/list-all-commands built-in yet — check the plugin's own README, or its entry.lua, for what it registers via register_command.

Can I use HomRec on Linux?

Not yet — see the Linux status page for what's planned.

Something in the older docs doesn't match what I'm seeing

That's expected for anything about Windows/Rules/AE Objects, hotkeys, or timers — that syntax predates the C++ rewrite and isn't implemented. This page reflects the current console; if something here is wrong, please let us know.