hilo
Open workspace

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 --version

Everyday

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. Normal onboarding performs this in the hosted workspace.

Agents

Command What it does
hilo agent new <name> [--owner <who>] Create a new agent, born in interview mode.
hilo agent ratify <name> Confirm it (the workspace’s Confirm button) — splices the interview section out.
hilo agent enable-index <name> Enable the agent’s memory index.
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 identity’s session folders after an agent changes machine or name.

Operations

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