CLI reference
One tool, two names. The installer puts both hilo and hilo-node on your PATH and
they are the same program — older material sometimes describes hilo as a separate
connector CLI, which it no longer is. Examples here use hilo.
It operates on the node home at $HILO_HOME, which defaults to ~/.hilo.
hilo --help
hilo --versionEveryday
| Command | What it does |
|---|---|
hilo doctor |
Health-check the node home, org store and config. The first thing to run when anything looks wrong. |
hilo observe |
Run the local fleet wallboard in the foreground. --url prints the authenticated local URL and exits. |
hilo node |
Run the daemon in the foreground. The installed service does this for you; use it to watch startup directly. |
hilo post <conversation> <text> |
Post a message into a conversation from a script or cron. |
hilo post is how scheduled work reports in:
hilo post <conversation-id> "Weekly report attached" --file report.md- reads the body from stdin. --file attaches a path as a versioned document and repeats
up to eight times — a ninth is a usage error rather than a silent drop. --thread <root-id>
posts into a thread, --agent <name> posts as an agent, and --wake triggers the
conversation rather than posting quietly.
Setup and pairing
| Command | What it does |
|---|---|
hilo tunnel pair --connection-file <file> |
Support-level command underneath the hosted installer. Customer onboarding runs it through the single instruction from Account → Customer Node Connection. |
hilo join <claim-url> |
Join an existing org as a relay sub-node, using a one-time claim link from the org’s Computers card. See More computers. |
hilo connect-account |
Support-level Claude authorization command for Claude Code agents. Normal onboarding performs this in the hosted workspace. Codex agents sign in with hilo codex login instead. |
Agents
| Command | What it does |
|---|---|
hilo agent new <name> [--owner <who>] |
Create a new Claude Code agent, born in interview mode. |
hilo agent new <name> --harness codex --owner <who> --actor <admin> |
Create a new Codex agent and start its ChatGPT sign-in. --codex-model and --codex-effort pick its model and thinking level; --creation-id resumes an interrupted creation. The runtime is permanent. |
hilo codex status [<name>] |
Without a name: the Codex CLI version this node supports and its Codex agents. With a name: that agent’s runtime, sign-in and native memory state. |
hilo codex login <name> |
Sign one Codex agent in with ChatGPT (device code; --browser for a browser sign-in). There is no node-wide Codex sign-in. |
hilo codex skills <name> |
List the native skills Codex discovered for an agent. |
hilo agent ratify <name> |
Confirm it (the workspace’s Confirm button) — splices the interview section out. |
hilo agent enable-index <name> |
Legacy opt-in for the old model-driven BYO indexing job; not the current included semantic-memory service. |
hilo adopt propose |
Read an adoption report as JSON from stdin and create a proposal. |
hilo adopt list |
List proposals waiting for a human decision. |
hilo adopt ratify <name> / refuse <name> |
Accept or refuse a copied agent. Refusal accepts --reason. |
hilo secrets list | set | unset | set-file | unset-file |
The per-agent credential store. --agent <name> scopes to one agent; without it the secret is node-wide. |
hilo roster refresh |
On a relay, re-discover local agent trees and propose additions to the main node. |
hilo migrate-sessions |
Re-key a moved Claude Code identity’s session folders after an agent changes machine or name. Codex agents are refused. |
Operations
For current memory consolidation and Hilo-funded semantic search, use the agent’s
Overview in the workspace. Do not add the legacy indexing job alongside the new
indexer. Agents retrieve notes through workspace_memory_search; see
Memory and maintenance.
| Command | What it does |
|---|---|
hilo update --check |
Report the available version and exit without applying. |
hilo update -y --target production |
Apply an update: backup, verify, auto-rollback on failure. |
hilo backup |
A verified archive of restorable node data, with credential values excluded. |
hilo backup --verify <archive> |
Verify an existing archive instead of making one. |
hilo backup --schedule <directory> |
Enable automatic verified backups outside HILO_HOME; cadence, retention and free-space floors are configurable. |
hilo backup --status / --disable-schedule |
Inspect or disable the automatic backup. |
hilo restore <archive> [--force] |
Restore a verified archive. Non-empty homes are refused unless --force is explicit. |
Detail on all three: Backups, updates and recovery.
Two things worth knowing
hilo secrets list prints names, never values. That is deliberate. If you need to know
whether a credential is correct, test it — reading it back tells you it exists, not that it
works. set reads the value from stdin rather than argv:
printf %s "$TOKEN" | hilo secrets set NAME --agent <agent>hilo backup always excludes credential values. A backup is the file most likely to
end up on someone’s cloud drive, so values stay out and only their names ride in the
manifest. Restore the data, then re-enter credentials and reconnect the node.
Next: Backups, updates and recovery · Agents
LAST UPDATED