Files
2026-10-09 14:35:12 -04:00

102 lines
4.1 KiB
Markdown

# CLI reference
One binary, `hermenix`:
| | For |
| -------------------------------- | ---------------------------------------------------------- |
| `hermenix setup` | host provisioning — disks, cache key, image |
| `hermenix migrate <src>` | existing flat `HERMES_HOME` → guest |
| `hermenix migrate connections` | connection files only |
| `hermenix remote <host> "<cmd>"` | `setup`/`migrate` over SSH |
| `hermenix vm <sub>` | VM lifecycle, snapshots, backups |
| `hermenix ctl <sub>` | host-side bridge into the guest (files, unit, passthrough) |
| `hermenix version` | packaged version string |
Quote multi-word remote/passthrough args as one string —
[CONCEPTS.md](CONCEPTS.md#quote-multi-word-subcommands).
Setup: [INSTALL.md](INSTALL.md). Migrate: [MIGRATE.md](MIGRATE.md).
---
## `hermenix vm`
```bash
hermenix vm ssh # interactive shell (vsock)
hermenix vm ssh "systemctl status" # run a command and exit
hermenix vm console # journalctl -u hermes-vm -f (read-only)
hermenix vm start | stop | restart
hermenix vm config # guest generation, history, git status
hermenix vm config-pull [dir] # copy guest /etc/nixos here
hermenix vm snapshot | snapshots
hermenix vm rollback <snap> # type 'rollback' to confirm
hermenix vm backup | backups
```
`console` is follow-only (no input). No interactive fallback if the guest is
dead.
Repo `guest/` is the **seed**; live guest `/etc/nixos` diverges after the
agent edits it. `config-pull` is for reading/diffing — a host rebuild will not
fix a guest config problem.
---
## `hermenix ctl`
Host-side helpers over vsock. They know where Hermes's files live in _this_
VM layout and how to reach the gateway unit — they are not a second Hermes
manual. For Hermes features (chat, sessions, providers, skills, …) use the
upstream CLI or [Hermes Agent docs](https://github.com/NousResearch/hermes-agent); unknown `ctl` words are
passed through to `hermes` in the guest.
```bash
# Files under hermesHome (default /var/lib/hermes/.hermes)
hermenix ctl soul [edit]
hermenix ctl memory [edit] # memories/USER.md if present
hermenix ctl conf [edit] # config.yaml
hermenix ctl secrets [edit|show] # .env, mode 0600; masked by default
# Gateway user unit (name: services.hermenix.gatewayUnit)
hermenix ctl status | logs | restart
hermenix ctl units
# Seed / fold-back (destructive where noted)
hermenix ctl reseed # overwrite from /etc/nixos/hermes seed
hermenix ctl pull [dir] # live home → host (no .env/sessions/state.db)
```
Passthrough examples (Hermes's own commands):
```bash
hermenix ctl chat
hermenix ctl update
hermenix ctl "sessions list"
hermenix ctl doctor
```
`edit` pulls over vsock, opens local `$EDITOR`, writes back, offers restart.
Secrets never enter the Nix store — no declarative option for them.
If `status`/`logs` are empty, check `hermenix ctl units` and set
`services.hermenix.gatewayUnit` to the real unit name.
`services.hermenix.hermesHome` is where `ctl` looks. Override for a flat
migrated layout; export `HERMES_HOME` inside the guest for the gateway
process if it differs from the default.
---
## Env baked in by the host module
| Env | Option | Default |
| ---------------------- | -------------------------------- | ------------------------- |
| `HERMES_VSOCK_CID` | `services.hermenix.vsockCid` | `77` |
| `HERMES_GUEST_NAME` | `services.hermenix.name` | `hermes` |
| `HERMES_DISK_BASE_DIR` | `services.hermenix.disk.baseDir` | `/var/lib/hermes-vm` |
| `HERMES_HOME_DIR` | `services.hermenix.hermesHome` | `/var/lib/hermes/.hermes` |
| `HERMES_GATEWAY_UNIT` | `services.hermenix.gatewayUnit` | `hermes-agent` |