soulctl

The operator’s client CLI — a thin wrapper over Keeper’s Operator API. The primary operator interface is OpenAPI and MCP; soulctl is a convenient CLI over the same HTTP endpoints, not a separate protocol.

Authentication

soulctl acts on behalf of an operator (Archon) via JWT. Credentials are stored in ~/.config/soul-stack/credentials.yaml (two fields: keeper_url and the operator token):

soulctl archon login     # save keeper_url + JWT (validated with a ping)
soulctl archon whoami     # current AID + permissions from the token claims
soulctl archon logout     # remove credentials.yaml

keeper_url points at Keeper’s Operator API (the HTTP listener, port 8080 by default). Global flags: --output table|json|yaml (-o) and --config (path to an alternative credentials file).

Command groups

soulctl is built from seven top-level groups:

Group	Purpose
incarnation	operations on incarnations (runtime instances of services)
souls	operations on the managed souls
soul	single actions on a specific agent
errand	the registry of one-off tasks (Errand): list / get / cancel
archon	operator authentication and identity
push-providers	managing the parameters of push-mode SSH plugins
run	run a scenario / ad-hoc cmd / push with universal targeting

incarnation

soulctl incarnation list                      # list incarnations
soulctl incarnation get <name>                # spec / state / status / covens
soulctl incarnation run <name> <scenario>     # run a scenario on the incarnation
soulctl incarnation history <name>            # state change history
soulctl incarnation check-drift <name>        # check the incarnation's drift

souls / soul

soulctl souls list                            # list registered agents
soulctl souls get <sid>                       # show an agent by SID
soulctl souls ssh-target set <sid> ...        # per-host push-mode SSH credentials
soulctl souls ssh-target bulk-set ...         # bulk-bind an SSH provider across a Coven
soulctl soul exec <sid> ...                   # a single module on a specific agent (Errand)

errand

soulctl errand list                           # list Errands with filters
soulctl errand get <errand_id>                # the Errand's state
soulctl errand cancel <errand_id>             # cancel an in-flight Errand

push-providers

soulctl push-providers create <name> ...      # create a Push-Provider record
soulctl push-providers list                   # list
soulctl push-providers get <name>             # read
soulctl push-providers update <name> ...      # replace params (replace semantics)
soulctl push-providers delete <name>          # delete

run

An umbrella for batch runs with unified targeting:

soulctl run scenario <service>/<scenario>     # batch scenario run over incarnations
soulctl run cmd '<command>'                   # ad-hoc shell command across N hosts
soulctl run push <destiny@ref>                # push-apply destiny through an SSH provider

Error handling

soulctl maps Operator API HTTP errors into a clear form: 401 → a soulctl archon login hint, 403 → a missing permission, 404 → not found, 5xx → keeper error.

The commands mirror the Operator API

soulctl carries no business logic of its own — each command calls the corresponding Operator API endpoint. The full set of operations (including those not surfaced in the CLI) is visible in Keeper’s OpenAPI spec at GET /docs.

Installation

soulctl does not ship as a deb/rpm package. Get it from a release binary or a source build (make build). See From binary releases and From source.