Local CLI
keel run applies one handler synchronously without contacting Kubernetes or
loading a kubeconfig. It uses the same handlers, templates and service restarts
as the daemon. Successful commands print {"changed":true} or
{"changed":false} and exit zero; failures print a diagnostic and exit nonzero.
There is no scheduling, Kubernetes status, metrics server or events in this mode.
Usage
make build
./bin/keel run --type file --host-root /tmp/keel-root \
--params '{"filename":"/etc/motd","contents":"Managed locally\n","mode":"0644"}'
--host-root defaults to /, so running with that default modifies the machine
on which the CLI runs. Use a temporary root to try file configurations safely.
Ordinary filesystem permissions apply; packages and services usually require
root. Roots other than / use chroot for commands, so the target needs its own
executables, libraries, package metadata and systemd connection.
| Option | Purpose |
|---|---|
--type |
Required registered handler (file or package) |
--params |
JSON object of string parameters |
--params-file |
Read the JSON object from a file instead of --params |
--host-root |
Absolute target root; defaults to / |
--facts-file |
Optional complete JSON Facts snapshot |
--service |
Service name or template to restart on change; repeat as needed |
Supply exactly one of --params and --params-file. JSON files avoid shell
quoting issues for multiline contents. Service templates are rendered and checked
before modifying the host; literal unit names, including instances such as
worker@node-a.service, are supported. Paths, whitespace, options and wildcards
are rejected.
Facts and templates
Without --facts-file, local facts contain hostname/name, kernel, runtime
architecture and /etc/os-release values read under the target root. Kubernetes
fields (labels, addresses, cluster identity and API version) are unavailable and
remain empty. Missing map keys and invalid template references fail the run.
To reproduce a cluster-specific template, supply an explicit snapshot:
{"Node":{"Name":"node-a","Hostname":"node-a","Labels":{"role":"worker"}},
"Cluster":{"Name":"lab","KubernetesVersion":"v1.36.0"}}
See facts and templates for all fields and helper signatures, and handlers for file/package behavior.
The supplied snapshot replaces local facts. Go template helpers are identical to the controller's helpers. Params and service template syntax are validated before execution; runtime facts references are checked when rendering.
Changes and errors
Service restarts happen only after a handler reports a change. The CLI has no persisted restart-pending state. If a restart fails after the configuration was applied, the command fails but the configuration remains applied; recover the service explicitly before relying on a later idempotent invocation. Commands use the caller's context and stop when the process receives a termination signal.