Previewkernable is not released yet: these docs describe work in progress, and things may change before 1.0.Not released yet.Request early access →
Skip to content

kernable (CLI) ​

The kernable command runs the kernel and does everything around it: it creates keys, grants and development certificates, revokes keys, applies a service's membership, lists what is registered, checks stores, and submits single commands for scripting. kernable without arguments prints this page as text. The flags of kernable start are in kernable start.

Commands that take an <addr> talk to a running kernel. Commands that take a <store> open the store file directly: the ones that only read it work while the kernel runs, the ones that change it need the kernel stopped.

Run the kernel ​

kernable start ​

text
kernable start --root <root.pub> [<flag> <value>]...
kernable start --dev [<flag> <value>]...

Runs the kernel in the foreground, trusting grants signed by the root keys; the flags are listed by kernable start --help. On Unix, SIGHUP reads the kernel key again. SIGTERM or SIGINT refuses new requests, lets running ones finish and stops; SIGTERM to a pair's primary hands its role to the standby in sync first. SIGUSR1 stops the same way, never handing over (a new binary takes the stores over). --dev is for trying kernable out: it creates root.key, kernel.key, vault.key, app.key and app.grant in the working directory if missing (app may do everything) and defaults to --root root.pub, --vault-key vault.key and --ui-listen 127.0.0.1:7234. Exit 2 on invalid flags; exit 1 if the kernel stops on an error.

kernable demo ​

text
kernable demo [--ui-listen <addr>]

Runs kernable for presentations: a kernel on a new store in a temporary directory, with a small bank built in, shown step by step on the Stage at http://<addr>/demo (default 127.0.0.1:7234). Reset starts again on a new store; Ctrl-C ends it and removes everything.

Keys and trust ​

kernable keys new ​

text
kernable keys new <name>

Writes <name>.key (the secret key, readable by the owner only, never overwritten) and <name>.pub (the key ID), and prints the key ID.

kernable grant ​

text
kernable grant <root.key> <name.pub> [--succeeds <old.pub>] <permission>...

Writes <name>.grant, signed by the root key, and prints its permissions. A permission is <action>=<type>,<type>... or a bare <type> for every action. Actions: submit run subscribe listen query answer check privileged vault_read vault_erase data_read data_write cache manage replicate export backup reserved_order. A type is *, <domain>.* or <domain>.<Type>; manage takes service names, privileged takes bypass_authorization; replicate, export, backup and reserved_order (negative listener orders, for kits) take *. --succeeds lets this key take over the aggregates and listeners registered with <old.pub>. A newer grant for the same key replaces the older one.

kernable revoke ​

text
kernable revoke <addr> <root.key> <key.pub> <since>

Revokes a key for good from <since> on (UTC, like 2026-10-27T09:00:00Z): the kernel refuses it, ends its connections and rejects its queued commands accepted since then (key_revoked). The kernel must be running.

kernable witness ​

text
kernable witness --listen <addr> --root <root.pub> --state <file> [--lease-ms <ms>] [--tls-...]

Runs the witness of a pair of kernels started with --witness: it decides which one is the primary, renews the primary's lease (3000 ms by default) and lets the standby in sync take its place when the lease runs out. It keeps the term and the roles in <file> (default witness.state); listens on 127.0.0.1:7300 by default, elsewhere only with mutual TLS (--tls-cert, --tls-key, --tls-client-ca).

kernable partitions apply ​

text
kernable partitions apply <addr> <key> <map.json>

Applies a partition map on the control partition at <addr>: {'epoch': 2, 'partitions': {'p1': ['host:7233'], 'p2': [...]}, 'default': 'p1', 'control': 'p1', 'tenants': {'acme': 'p2'}} (JSON, with double quotes). Tenants not listed live on the default partition; the epoch must grow with every map. <key> needs a grant for manage on *. The other partitions take it from the control partition.

kernable partitions show ​

text
kernable partitions show <addr> <key>

Prints the partition map the kernel at <addr> holds.

kernable partitions move ​

text
kernable partitions move <addr> <key> <tenant> <to>

Moves <tenant> with its data to partition <to>: applies a map that marks it moving on the control partition at <addr>, waits until <to> has copied it, then applies the map with the tenant on <to>. Meanwhile the tenant's requests are answered UNAVAILABLE. Run it again to finish a move it did not. <key> needs manage on *.

kernable promote ​

text
kernable promote <addr> <key>

Makes the standby at <addr> (started with --follow) the primary: it stops following and serves. <key> needs a grant for manage on *. Promote only a standby whose primary is gone: a primary that still runs is fenced (it tells nobody of a write from then on), and rejoins as a standby of the new one. Without a witness, a standby the primary never told it is in sync is refused: the primary may have told writes it lacks.

kernable switchover ​

text
kernable switchover <addr> <key>

Hands the primary role over to the standby in sync now: the primary at <addr> refuses new requests (the SDKs retry them on the other kernel), lets running ones finish, and waits until the standby holds every record (at most 10 s). In a pair (--witness) it tells the witness; without one it tells the standby on its stream. The standby serves at once, and the old primary stops: in a pair, started again, it follows; without a witness, it starts only with --follow. For updates and moves: update or start the standby, switch over, update or retire the old primary. <key> needs a grant for manage on *.

kernable certs new ​

text
kernable certs new <dir> <client>...

Writes a development CA (ca.tls.crt), a kernel certificate (kernel.tls.crt, kernel.tls.key) and a certificate per <client> (<client>.tls.crt, <client>.tls.key) to <dir>, for mutual TLS. The CA key is not kept: issue a new set to add clients. Production brings its own PKI.

Deploy and inspect ​

kernable apply ​

text
kernable apply <addr> <key> <manifest.json>

Applies a service's membership: a JSON manifest with service, workers, listeners, middlewares, processes and metadata. A process the service's membership listed before and no longer lists starts no new cases. Signed with <key>, whose grant needs manage=<service>; the grant file next to the key (app.grant for app.key) is sent along. The kernel must be running. Once per deploy.

kernable services ​

text
kernable services <store>

Lists each applied membership: the service, its metadata, who applied it and when, and the workers, listeners and middlewares it lists, marking those that never registered; then the service's dynamic listeners, registered but not listed.

kernable workers ​

text
kernable workers <store>

Lists the registered aggregate types with their command types, key, service and when a worker for them was last seen.

kernable listeners ​

text
kernable listeners <store>

Lists the registered listeners with order, position, event types, key, service, middleware and when they were last seen. A listener its service's membership does not list is marked: it counts for nobody.

kernable listeners parked ​

text
kernable listeners parked <store>

Lists the events listeners parked: the listener, position, event type, code, attempts, when, whether a retry is asked for, and the message (for a handler error only the error's type; the listener's log has the rest).

kernable schemas ​

text
kernable schemas <store>

Lists the highest stored schema version per event type.

kernable processes list ​

text
kernable processes list <store>

Lists the registered business processes: name, newest version, state (active or removed), as whom it acts (ProcessService.Act; else process:<name>), and when and by which key the newest version was registered.

kernable processes show ​

text
kernable processes show <store> <name> [<version>]

Prints a process's model as registered, the newest version or <version>, as indented JSON. Exit 1 if there is no such process or version.

kernable processes cases ​

text
kernable processes cases <store> <process> [--state running|waiting|incident|ended]

Lists the cases of a process: tenant, case ID, state (running: a command sent or a query asked; waiting: for an event or a time; incident; ended) and the step it is at (or how it ended). Reads every event, also with the kernel stopped; the UI's Processes view shows them live.

kernable processes case ​

text
kernable processes case <store> <process> <case>

Prints a case's events as a timeline: when, version, event type and its data.

Processes, with the kernel running ​

kernable processes retry|skip|cancel ​

text
kernable processes retry|skip|cancel <addr> <key> <process> <case> [--tenant <tenant>]

Resolves a case's incident: retry runs its step again, skip goes on to the step's next step, cancel ends the case (also without an incident). Signed with <key>, whose grant needs process=<process>; the grant file next to the key is sent along. --tenant names the case's tenant when its ID is used in several.

kernable processes remove ​

text
kernable processes remove <addr> <key> <name>

Removes a process: it starts no new cases, its running cases finish; registering it again makes it active. Signed with <key>, whose grant needs process=<name>; the grant file next to the key is sent along. Exit 1 if it was removed already.

Parked events, with the kernel running ​

kernable listeners retry ​

text
kernable listeners retry <addr> <key> <listener> <position|--all>

Delivers the listener's parked event at <position> again, or all of them, the next time it is connected; if it fails again, it is parked again. Signed with <key>, whose grant needs manage=<service> of the listener (manage=* for one without a service); the grant file next to the key is sent along. Exit 1 if none of them is parked.

kernable listeners dismiss ​

text
kernable listeners dismiss <addr> <key> <listener> <position|--all>

Removes the parked event at <position>, or all of them, without delivering them again. Like retry otherwise.

Check the store ​

kernable verify ​

text
kernable verify <store> <kernel.pub>...

Recomputes the hash chain and checks every checkpoint and signature, with every key the kernel ever had: give all its .pub files. Read-only, so the kernel may run. Prints the counts, PROBLEM and SUSPECT lines, then OK or TAMPERED. Exit 0: intact. Exit 1: tampered, or the check failed. Exit 2: intact, but something was signed by a key at or after its revocation (SUSPECT lines). Events after the last checkpoint are counted: cutting them off could not be detected.

kernable checkpoint ​

text
kernable checkpoint <store> <kernel.key>

Signs a checkpoint of the newest event now, as the running kernel does every --checkpoint-interval-ms. Kernel stopped.

Export and import ​

kernable export ​

text
kernable export <addr> <key> <file>

Writes everything the running kernel at <addr> holds to <file>: every record of its store, every file of its data store and the vault values, which stay encrypted with its vault key. The kernel signs a checkpoint first. <key> needs a grant for export on *; the grant file next to the key is sent along. <file> must not exist; it is written readable by its owner only, and deleted if the export does not finish. Snapshots and the cache are not exported. Prints the counts and the kernel keys that signed the store.

kernable export ​

text
kernable export <file> [--store <s>] [--data-store <d>] [--vault-store <v> --vault-key <k>]

The same from stores read directly, kernel stopped. The flags name the stores as for kernable start, with its defaults; without --vault-key the vault is left out, which fails if the store refers to vault values.

kernable import ​

text
kernable import <file> [--store <s>] [--data-store <d>] [--vault-store <v> --vault-key <k>] [--kernel-pub <kernel.pub>]...

Fills new, empty stores from an export, then checks the store like verify, with the same output and exit codes. --vault-key must be the source's vault key. The whole file is checked before anything is written: a copy cut short or changed, or a wrong vault key, is refused. Without --kernel-pub, the store is checked with the kernel keys the export names; compare them with the source's .pub files, or name those. Keep the source's kernel .pub files for verify after the kernel runs on the new stores.

Run a node ​

kernable node ​

text
kernable node <project.toml>

Runs one node of a project: the kernel and, with a [backup] section, the backup follower, as child processes it restarts when they exit. It reads the file again every two seconds or on SIGHUP, and restarts a child whose command changed or whose binary was replaced. SIGTERM or SIGINT stops the children (SIGKILL after stop-seconds, default 30). The file has [kernel] (flags: the flags of kernable start without their dashes, env, binary, stop-seconds), [backup] (to, key, backup-key, follow, segment-seconds, base-hours, keep, check-hours, env), [node] (instance, project, podman, metrics-listen: GET /metrics) and any number of [[service]] (name, build, file, command, key, env, secrets, cpus, memory, stop-seconds, writable, expose): containers built with podman on the node, rebuilt on SIGHUP, run after the kernel with KERNABLE_URL, KERNABLE_INSTANCE and their key. Every child's output comes out of the node prefixed with its name. Paths are relative to its directory. Exit 2 if the file is invalid at start.

kernable expose ​

text
kernable expose <socket>=<host:port>... Passes every connection to each Unix socket on to its

address, both ways: a node runs it in an instance's pod, for a service's port to be reached through the socket.

Continuous backup ​

kernable backup key ​

text
kernable backup key <file>

Writes a new backup key (32 random bytes in hex) to <file>, readable by its owner only; never overwrites one. Keep it apart from the backups, as you keep the root key: without it a backup cannot be read.

kernable backup ​

text
kernable backup --follow <addr>[,<addr>] --key <key> --to <target> --backup-key <file> [--segment-seconds <s>] [--base-hours <h>] [--keep <n>] [--check-hours <h>] [--status-file <file>]

Follows the kernel at <addr> (started with --backup on; both kernels of a pair, comma-separated) and writes its records to <target>, encrypted with the backup key, until stopped: a base, then a segment every --segment-seconds (default 5) or 16 MiB, a new generation every --base-hours (default 24), the newest --keep (default 7) kept. <key> needs a grant for backup on *; the grant file next to it is sent along. <target> is file:<dir> or s3://<bucket>/<prefix>, with KERNABLE_S3_ENDPOINT, KERNABLE_S3_REGION, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. Vault values stay encrypted with the kernel's vault key besides. With --check-hours, it also checks the backup that often, as backup check does, and logs what it found. With --status-file, it notes there (JSON) when it last uploaded, up to which record, and when it last checked and what it found.

kernable backup list ​

text
kernable backup list <target> --backup-key <file>

Prints the generations of a backup: each base's record and time, and how far its segments reach.

kernable backup check ​

text
kernable backup check <target> --backup-key <file>

Reads the newest generation all through, without writing a store: every object opens with the key and decodes, and the records chain from the base to the last segment. Prints the record a restore reaches and how old it is; exits 1 if the backup does not check out.

kernable restore ​

text
kernable restore <target> --backup-key <file> [--at <time> | --at-record <n>] [--store <s>] [--data-store <d>] [--vault-store <v> --vault-key <k>] [--kernel-pub <kernel.pub>]...

Fills new, empty stores from a backup: the newest generation that begins before --at (UTC, like 2026-11-04T13:40:00Z) or --at-record, its base, then its segments up to there (default: everything), then checks the store like verify, with the same output and exit codes. --vault-key must be the source's vault key; the flags name the stores as for kernable start. Without --kernel-pub, the store is checked with the kernel keys the backup names.

Maintenance, with the kernel stopped ​

kernable listeners remove ​

text
kernable listeners remove <store> <name>

Removes a listener and its middleware, so they no longer count. If a listener connects again under that name, it starts at the newest event. Exit 1 if there is no such listener.

kernable workers remove ​

text
kernable workers remove <store> <domain.Aggregate>

Unregisters an aggregate type: its commands are refused (NOT_FOUND) unless a membership lists it. Exit 1 if there is no such aggregate.

kernable vault rekey ​

text
kernable vault rekey <vault> <old.key> <new.key>

Re-encrypts every vault value with a new key; then start the kernel with --vault-key <new.key>. <vault> is the --vault-store, for example sqlite:vault.db. A key encrypts at most 2^32 values (each with a random nonce): the kernel warns at startup past half of that and refuses new values at the limit, until the vault is rekeyed.

Scripting ​

kernable ​

text
kernable --version

Prints the version, the system and the architecture.

kernable submit ​

text
kernable submit <addr> <client.key> <tenant> <domain> <aggregate_type> <aggregate_id> <command_type> <payload>

Signs a command with a new ID and submits it, waiting until it has settled; the grant file next to the key is sent along. <payload> is sent as given, usually JSON. Prints the command ID, then a committed line per event with its global position, version, type and payload, or rejected <code>: <message> with exit 1. It cannot seal vault fields: not for commands with personal or secret values.

Arguments and exit codes ​

<addr> is host:port, http://host:port, or unix:<path> on Unix. To reach a kernel over mutual TLS, set KERNABLE_TLS_CA, KERNABLE_TLS_CERT and KERNABLE_TLS_KEY to PEM files, as for the SDKs. <store> is the kernel's --store: sqlite:<path>, a bare SQLite path, or file:<path>. Exit codes, unless a command says otherwise: 0 success, 1 failure, 2 unknown command or wrong arguments.