102 lines
4.1 KiB
Markdown
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` |
|