Command reference
Host lifecycle CLI
The commands that create, replace, recover, start, stop, and reconfigure a self-hosted Kern host.
Commands
Every lifecycle command is a Python module in the Kern checkout and takes the host name you deployed with. Only the verb changes.
bash
python3 -m host.cli.<verb> --agent-name <name>| Verb | Effect | Flags beyond the shared ones |
|---|---|---|
deploy | Create a new host. Fails if an instance or data volumes already exist. | --admin-password-sha256 (required), and at least one operator endpoint: --operator-ssh-public-key or --operator-cloudflare-hostname |
upgrade | Advance preserved state to the target version without changing the admin password or operator access. | None |
recover | Create a replacement from preserved volumes when no instance exists. | --allow-upgrade to also advance preserved state to the target version |
reconfigure | Replace the operator endpoints and refresh the admin password for preserved state. | Same endpoint and password flags as deploy, plus --reset-admin-passkeys |
start | Start the existing instance and wait until it is running. | None |
stop | Stop the existing instance and wait until it is stopped. | None |
| Shared flag | Meaning |
|---|---|
--agent-name | Required. The stable host name, 1 to 50 characters of letters, numbers, - or _. |
--provider | aws by default, which provisions EC2 and EBS. Use lima for a local VM with durable Lima data disks. |
--bootstrap-from-github | Provision from a pinned public commit instead of pushing your local checkout over SSH. With no value it pins the latest main commit and asks you to confirm the version. Available on deploy, upgrade, recover, and reconfigure, not on start or stop. |
Operational notes
- Run lifecycle commands from a Kern repository checkout at the version you intend to deploy.
- Keep plaintext secrets in environment variables or stdin where the command requires them; do not put tunnel tokens in CLI arguments.
- Save deployment JSON and the admin password in operator-controlled storage.
- Read the command result before retrying. A partial cloud operation may have created resources that change the correct next verb.