CLI Reference

cloacinactl is the command-line interface for Cloacina. It manages local services (daemon, server, compiler), talks to the HTTP API as a client, and edits the local config file at ~/.cloacina/config.toml.

The command shape is a strict noun-verb pattern, with a handful of top-level singletons (status, config, admin, completions).

Synopsis

cloacinactl [GLOBAL FLAGS] <noun> <verb> [ARGS]
cloacinactl [GLOBAL FLAGS] <singleton> [ARGS]

Global Flags

These flags apply to every subcommand.

Flag	Default	Description
`-v`, `--verbose`	`false`	Enable debug-level logging on stderr.
`--home <PATH>`	`~/.cloacina`	Override the Cloacina home directory. Affects all home-relative paths (config, logs, packages, sockets, PID files, bootstrap key).
`--profile <NAME>`	(default profile from config)	Select a named profile from `~/.cloacina/config.toml`. Resolves the server URL and API key.
`--server <URL>`	(from profile)	Override the profile’s server URL. Highest precedence among server-targeting flags.
`--api-key <KEY>`	(from profile)	Override the profile’s API key. Supports the API key schemes below.
`--tenant <NAME>`	`public`	Tenant name for tenant-scoped commands. Defaults to the admin “public” schema if unset.
`--json`	`false`	Shorthand for `-o json`.
`-o`, `--output <FORMAT>`	`table`	Output format: `table`, `json`, `yaml`, or `id`.
`--no-color`	`false`	Accepted, but currently a no-op — no code path reads it yet.

API Key Schemes

--api-key and the api_key profile field accept several schemes:

Scheme	Example	Behavior
Raw	`clk_a1b2c3...`	The literal API key.
`env:VAR`	`env:CLOACINA_API_KEY`	Read the key from the named environment variable. Errors if the variable is unset or empty.
`file:PATH`	`file:/etc/cloacina/key`	Read the first non-empty line of the file. Whitespace is trimmed.
`keyring:NAME`	`keyring:prod`	Deferred; rejected today with a clear error message.

Output Formats

Format	Behavior
`table` (default)	Human-readable aligned columns. Long strings are truncated with `…`. Auto-infers columns from the first object’s keys; not ideal for deeply-nested resources.
`json`	Pretty-printed JSON, one document per response.
`yaml`	YAML output, one document per response.
`id`	One ID per line. Extracts the `id` or `name` field from each object. Useful in shell pipelines: `cloacinactl execution list -o id \| xargs -n1 cloacinactl execution status`.

Exit Codes

cloacinactl uses a fixed mapping (per ADR-0003 §6) so scripts can distinguish failure modes:

Code	Meaning
`0`	Success.
`1`	User error: bad flags, missing files, validation failure, local I/O failure.
`2`	Network/transport failure: unreachable daemon socket, HTTP connection refused.
`3`	Resource not found (HTTP 404).
`4`	Authentication failure (HTTP 401/403).
`5`	Server-side rejection (HTTP 4xx/5xx other than 404/401/403).

Environment Variables

Variable	Used By	Description
`DATABASE_URL`	`server start`, `compiler start`, `admin cleanup-events`	PostgreSQL or SQLite connection URL. Overridden by the corresponding `--database-url` flag where applicable.
`CLOACINA_BOOTSTRAP_KEY`	`server start`	Pre-supplied bootstrap admin key. If unset and no keys exist, one is generated. Overridden by `--bootstrap-key`.
`CLOACINA_REQUIRE_SIGNATURES`	`server start`	If `true`, the server enforces package signature verification at upload. Overridden by `--require-signatures`.
`RUST_LOG`	All commands	Log filter directive (e.g., `info`, `debug`, `cloacina=debug`). Overridden by `-v` / `--verbose`.
`OTEL_EXPORTER_OTLP_ENDPOINT`	`server start`	If set, enables OpenTelemetry tracing to the named gRPC collector.
`OTEL_SERVICE_NAME`	`server start`	Service name in OpenTelemetry spans. Default: `cloacina`.
`CLOACINA_VAR_<NAME>`	Workflow context	Read by `cloacina::var("NAME")` / `var_or` in Rust and `cloaca.var("NAME")` in Python; the `CLOACINA_VAR_` prefix is mandatory.
`CLOACINA_DEFAULT_EXECUTOR`	`server start`	Executor key for dispatch (`default` or `fleet`). Overridden by `--default-executor`; overrides `[server].default_executor`.

Service Commands

These commands manage local services. daemon start runs the daemon in the foreground, in-process (there is no built-in daemonize); server start and compiler start exec the corresponding binary from PATH. All write a PID file under --home first, and stop / status / health resolve that same --home — mixing --home values between start and stop silently misses the process.

`daemon`

The daemon is a lightweight local scheduler. It watches directories for .cloacina packages, runs the reconciler, and registers cron + custom-poll trigger schedules. State lives in ~/.cloacina/cloacina.db (SQLite, WAL mode). The daemon does not expose an HTTP API; it exposes a Unix-domain health socket at ~/.cloacina/daemon.sock.

`daemon start`

cloacinactl daemon start [--watch-dir <DIR>]... [--poll-interval <MS>]

Flag	Default	Description
`--watch-dir <DIR>`	(none)	Additional package directory to watch. Repeatable. The default watch dir (`~/.cloacina/packages/`) is always included; CLI dirs and config dirs are merged and deduplicated.
`--poll-interval <MS>`	`500`	Reconciler fallback poll interval in milliseconds. The filesystem watcher provides immediate detection; this is the safety net.
`--log-retention-days <N>`	`14`	Number of daily-rotated log files to retain in `~/.cloacina/logs/`. `0` disables pruning. CLOACI-I-0109 / T-0592.

Behavior:

Creates ~/.cloacina/{packages,logs}/ if missing.
Sets up dual logging: stderr (human-readable) + ~/.cloacina/logs/cloacina.log (JSON, daily rotation).
Opens or creates ~/.cloacina/cloacina.db (SQLite, WAL mode).
Loads ~/.cloacina/config.toml if present.
Builds the merged watch-directory set (default + CLI + config).
Initializes a DefaultRunner (cron + trigger schedulers, intervals from config).
Initializes a FilesystemWorkflowRegistry across all watch dirs.
Performs an initial reconciliation (loads existing packages).
Starts the health socket at ~/.cloacina/daemon.sock.
Enters the event loop: filesystem changes (debounced) trigger reconciliation; --poll-interval is the periodic fallback.

Signals:

Signal	Behavior
SIGINT (Ctrl-C)	Graceful shutdown. Drains in-flight workflows up to `daemon.shutdown_timeout_s`. Exit 0.
SIGTERM	Same as SIGINT.
SIGHUP	Reload `config.toml`, update watch directories, trigger reconciliation. No restart.
Second SIGINT during shutdown	Force immediate exit. Exit 1.

`daemon stop`

cloacinactl daemon stop [--force]

Reads the daemon’s PID file and sends SIGTERM (or SIGKILL with --force). Exit 0 if stopped cleanly; exit 2 if the PID file is missing or the process is unreachable.

`daemon status`

cloacinactl daemon status

Connects to ~/.cloacina/daemon.sock and prints a status table: health, uptime, packages loaded, last reconciliation. Respects --no-color.

`daemon health`

cloacinactl daemon health

Terse health probe via the Unix socket at ~/.cloacina/daemon.sock (or <home>/daemon.sock if --home is set). No output. Exit 0 if up, 2 otherwise. Use this in scripts and supervisor checks.

`server`

The HTTP API server (cloacina-server). Backed by PostgreSQL or SQLite. Exposes the HTTP API under the /v1/ prefix and the unauth probes /health, /ready, /metrics.

`server start`

cloacinactl server start [--bind <ADDR>] [--database-url <URL>]
                        [--bootstrap-key <KEY>]
                        [--require-signatures] [--verification-org-id <UUID>]
                        [--reconcile-interval-s <N>]
                        [--tenant-runner-cache-size <N>]
                        [--tenant-deletion-drain-timeout-s <N>]
                        [--log-retention-days <N>]

Flag	Env Var	Default	Description
`--bind <ADDR>`		`127.0.0.1:8080`	Listen address.
`--database-url <URL>`	`DATABASE_URL`	(required)	Database connection URL. Examples: `sqlite:///path/to/cloacina.db`, `postgres://user:pass@host/dbname`.
`--bootstrap-key <KEY>`	`CLOACINA_BOOTSTRAP_KEY`	(auto-generated)	Pre-supplied admin key for first startup. If a key is generated, the plaintext is written to `~/.cloacina/bootstrap-key` with `0600` perms exactly once.
`--require-signatures`	`CLOACINA_REQUIRE_SIGNATURES`	`false`	Enforce package signature verification at upload time. Requires `--verification-org-id`. CLOACI-I-0103.
`--verification-org-id <UUID>`	`CLOACINA_VERIFICATION_ORG_ID`	(none)	Trusted organization UUID used to verify package signatures. Required when `--require-signatures` is set; startup fails fast otherwise. CLOACI-I-0103 / T-0567.
`--reconcile-interval-s <N>`		(runtime default)	Interval (seconds) between reconciler passes that sync the in-runner workflow registry with the DB. Increase for quiet prod; decrease for fast e2e tests.
`--tenant-runner-cache-size <N>`	`CLOACINA_TENANT_RUNNER_CACHE_SIZE`	`256`	LRU cap on cached per-tenant `DefaultRunner` instances. Each cached runner has its own scheduler loop, executor pool, and DB connection pool. Bump for high-cardinality SaaS deployments; drop for memory-tight ones. CLOACI-T-0580.
`--tenant-deletion-drain-timeout-s <N>`	`CLOACINA_TENANT_DELETION_DRAIN_TIMEOUT_S`	`30`	Max seconds to wait for in-flight workflows to drain during tenant teardown (step 2 of the 4-step orchestration). Past this, the runner is hard-evicted; any task that ignored cooperative cancellation errors on its next DB write once the schema is dropped. CLOACI-T-0581.
`--log-retention-days <N>`		`14`	Number of daily-rotated log files to retain. `0` disables pruning entirely. CLOACI-I-0109 / T-0592.

This subcommand was renamed from serve in an earlier release; older docs may still mention the old name.

server start execs the cloacina-server binary from PATH (after writing <home>/server.pid). The install script installs only cloacinactl — if cloacina-server is not separately installed (container image or cargo), server start fails with “failed to exec cloacina-server”. The wrapper resolves database_url and [server].default_executor from config.toml and forwards them as flags; other runtime-tuning knobs are not surfaced through the wrapper — if you need to tune them, invoke cloacina-server directly.

Default executor (`cloacinactl server start` + `cloacina-server`)

Execution topology is a single deployment knob (CLOACI-T-0640). The preferred way to set it is [server].default_executor in config.toml; cloacinactl server start reads it and forwards --default-executor to cloacina-server. The flag/env below override the config value for ad-hoc runs. The key is hard-matched against the registered executors at startup — an unknown key fails fast.

Flag	Env Var	Default	Description
`--default-executor <KEY>`	`CLOACINA_DEFAULT_EXECUTOR`	`default`	Executor every task is dispatched to. `default` runs all work on the in-process thread executor; `fleet` sends it to the execution-agent fleet. Forwarded by `cloacinactl server start`; also settable directly on `cloacina-server`. CLOACI-T-0640.

Fleet agent liveness (`cloacina-server`)

These flags tune the execution-agent fleet. They live on the cloacina-server binary directly (and via the env vars below); the cloacinactl server start wrapper does not forward them, so set them on cloacina-server itself or through the environment.

Flag	Env Var	Default	Description
`--agent-heartbeat-interval-s <N>`	`CLOACINA_AGENT_HEARTBEAT_INTERVAL_S`	`15`	Heartbeat interval (seconds) advertised to agents and used as the liveness-sweep cadence. Lower = faster dead-agent detection + in-flight reclaim, more heartbeat traffic. CLOACI-T-0639.
`--agent-liveness-misses <N>`	`CLOACINA_AGENT_LIVENESS_MISSES`	`3`	Consecutive missed heartbeats before an agent is declared dead and its in-flight work reclaimed. Effective dead-after = interval × misses (default 45s). CLOACI-T-0639.

`server stop` / `status` / `health`

Same shape as the daemon equivalents, but use the server’s PID file for stop and HTTP probes for the rest: both status and health hit GET /health on the resolved profile server (status prints “server: unconfigured” when no profile/--server is set; health exits 0 if up, 2 otherwise).

`compiler`

The compilation service (cloacina-compiler). Polls the database for uploaded packages with build_status = pending and compiles their source into cdylib artifacts stored back in the database. Like server start, compiler start execs the cloacina-compiler binary from PATH (after writing <home>/compiler.pid).

`compiler start` / `stop` / `status` / `health`

cloacinactl compiler start [--bind <ADDR>] [--database-url <URL>]
                          [--poll-interval-ms <N>]
                          [--heartbeat-interval-s <N>]
                          [--stale-threshold-s <N>]
                          [--sweep-interval-s <N>]

Flag	Default	Description
`--bind <ADDR>`	`127.0.0.1:9000`	Listen address.
`--database-url <URL>`	from `DATABASE_URL`	Connection URL (Postgres or SQLite).
`--poll-interval-ms`	(binary default)	How often to poll for pending build rows.
`--heartbeat-interval-s`	(binary default)	Worker heartbeat cadence.
`--stale-threshold-s`	(binary default)	Seconds before an in-flight build is considered stale and reclaimable.
`--sweep-interval-s`	(binary default)	How often to sweep for stale claims.

stop / status / health follow the same pattern as server: PID file for stop, HTTP GET /v1/status for status, HTTP GET /health for health. Note: compiler status / health probe the address in [compiler].local_addr from config.toml (default 127.0.0.1:9000), not the --bind you passed to compiler start — if you started the compiler on a non-default bind, set compiler.local_addr to match or status will report unreachable.

`agent`

The execution-agent (cloacina-agent) is a DB-less worker that joins a server’s fleet. It registers over REST, opens the delivery WebSocket, fetches compiled workflow cdylibs by digest, executes the task in-process, and reports the result back — holding no database connection of its own. It is a standalone binary, not a cloacinactl subcommand.

cloacina-agent --server <URL> --api-key <KEY>
               [--agent-id <ID>] [--max-concurrency <N>]
               [--capabilities <TAG,TAG>] [--target-triple-override <TRIPLE>]
               [--cache-dir <PATH>]

Flag	Env Var	Default	Description
`--server <URL>`	`CLOACINA_SERVER`	(required)	Base URL of the server to register with (REST + WS ticket mint).
`--api-key <KEY>`	`CLOACINA_API_KEY`	(required)	API key for REST + WS auth. Its tenant scope determines which tenants’ work the agent may receive (REQ-008).
`--agent-id <ID>`		(server-assigned)	Optional caller-chosen agent id. If omitted, the server assigns one.
`--max-concurrency <N>`		`4`	Max work packets the agent runs concurrently. The server’s capacity-aware selection won’t exceed this; a saturated agent refuses further packets.
`--capabilities <TAG,TAG>`		(none)	Free-form capability tags advertised at registration.
`--target-triple-override <TRIPLE>`		(host triple)	Override the advertised host target triple. Rarely needed — the server only dispatches a cdylib built for the agent’s triple (OQ-6 fail-closed), so this is mainly for testing that path.
`--cache-dir <PATH>`	`CLOACINA_AGENT_CACHE_DIR`	`<TMPDIR>/cloacina-agent-cache`	Where fetched cdylibs are cached by digest; a cache hit skips the REST fetch.

The agent exposes no HTTP surface of its own — observe it via its logs and the server’s fleet metrics (cloacina_fleet_*). See the how-to guide Deploy an execution-agent fleet.

Client Commands

These commands talk to a running cloacina-server over HTTP. They respect the global --profile / --server / --api-key / --tenant flags. All require authentication except where noted.

`package`

`package new <NAME> [--lang <LANG>] [--kind <KIND>] [--path <DIR>]`

Scaffolds a canonical package source tree. Local-only.

Flag	Default	Description
`--lang <python\|rust>`	`python`	Source language to scaffold.
`--kind <workflow\|graph\|cron>`	`workflow`	Package shape. All three kinds scaffold for both languages; `cron` emits a workflow bound to a cron trigger (`#[trigger(on, cron)]` in Rust, `@cloaca.trigger(on=..., cron=...)` in Python).
`--path <DIR>`	`./<name>`	Directory to create.

`package build <DIR> [--release]`

Runs cargo build in <DIR> (must contain a Cargo.toml and package.toml). With --release, builds the release profile. Default is debug. Local-only; does not contact the server. Exits 1 on missing files or build failure. A no-op for Python packages.

`package validate <PATH>`

Validates a package — a source directory or a .cloacina archive — against the canonical format without uploading. Checks the resolved manifest (closed schema), the language layout (Rust Cargo.toml+src/lib.rs vs Python workflow/ tree), and lints known footguns (unrewritten __WORKSPACE__ placeholders, #[computation_graph] without graph_name, a cron trigger duplicated in #[workflow(triggers = ...)]). Local-only.

`package pack <DIR> [--out <PATH>] [--sign <KEY>]`

Packs the source directory into a .cloacina archive (tar + bzip2 source archive — no compiled artifacts). --out defaults to <dir>/<name>.cloacina. Runs the same validation as package validate first.

--sign <KEYFILE> fails hard by design: workflow-package signing is not yet implemented (tracked under CLOACI-I-0103), so passing --sign produces an error rather than a silently unsigned archive. Note the asymmetry: the server’s --require-signatures enforcement exists, so a server requiring signatures cannot accept packages packed by this CLI until I-0103 lands (signature rows must be inserted out-of-band).

`package publish <DIR> [--release] [--sign <KEY>]`

build → pack → upload in one shot. --sign fails hard, same as package pack.

`package upload <FILE>`

Multipart POST of a .cloacina archive to /v1/tenants/<tenant>/workflows. Requires a resolved server + API key (profile or flags). Server-side signature verification is enforced if the server was started with --require-signatures. Exit codes: 1 (user error), 2 (network), 4 (auth), 5 (server reject).

`package list [--filter <SUBSTRING>]`

GET /v1/tenants/<tenant>/workflows. The --filter is applied client-side as a substring match on the package name.

`package inspect <ID>`

GET /v1/tenants/<tenant>/workflows/<id>. Prints a single object respecting --output.

`package delete <ID> [--force]`

Resolves the package via GET /v1/tenants/<tenant>/workflows/<id>, then issues DELETE /v1/tenants/<tenant>/workflows/<name>/<version>. Interactive confirmation unless --force.

`constructor`

Packages a #[constructor] provider crate into a .cloacina provider archive (CLOACI-T-0827). Providers are the plugin crates that constructor!(from = "provider@version", ...) nodes resolve against. Local-only (builds with cargo; no server contact).

`constructor package <CRATE-DIR>`

cloacinactl constructor package <CRATE-DIR> [--out <PATH>]
    [--sign-key <FILE>] [--manifest-bin <NAME>] [--debug] [--native]

Flag	Default	Description
`--out <PATH>`	`<name>-<version>.cloacina` in CWD	Output archive path.
`--sign-key <FILE>`	(none)	Ed25519 secret key (32 raw bytes) used to sign the provider archive (`package.sig`). This provider-side signing scheme is implemented — distinct from the unimplemented workflow-package `--sign`.
`--manifest-bin <NAME>`	`emit_manifest`	Name of the provider crate’s `[[bin]]` that prints the generated provider manifest JSON.
`--debug`	off	Build the component in debug profile (default is release).
`--native`	off	Package a native host cdylib provider instead of a sandboxed wasm32-wasip2 component (CLOACI-T-0903). Native providers run trusted and unsandboxed in-process — capability grants are advisory, not enforced. The crate must declare a `native` cargo feature plus fidius-core/fidius-macro host deps. The command prints the trust tier to stderr.

`workflow`

Command	HTTP Endpoint	Notes
`workflow list [--package <FILTER>]`	`GET /v1/tenants/<tenant>/workflows`	Client-side `--package` substring filter on the package name.
`workflow inspect <NAME>`	`GET /v1/tenants/<tenant>/workflows/<name>`	Full workflow metadata: tasks, dependencies, trigger rules, schedules.
`workflow run <NAME> [--context <SOURCE>]`	`POST /v1/tenants/<tenant>/workflows/<name>/execute`	`--context` accepts a path to a JSON file or `-` for stdin. Defaults to `{}`. JSON is validated before submission. Prints the execution ID.

`execution`

Command	HTTP Endpoint	Notes
`execution list [--workflow <F>] [--status <S>] [--limit <N>] [--offset <N>]`	`GET /v1/tenants/<tenant>/executions?status=…&workflow=…&limit=…&offset=…`	Default limit: 50, server cap 1000; default offset 0. `--status` and `--workflow` map to the server query params of the same names (CLOACI-T-0594 / API-02).
`execution status <ID>`	`GET /v1/tenants/<tenant>/executions/<id>`	Returns Pending / Running / Completed / Failed / Cancelled / Paused.
`execution events <ID> [--since <DURATION>] [--follow]`	`GET /v1/tenants/<tenant>/executions/<id>/events?since=<dur>`	`--follow` streams live events over the server’s WebSocket delivery substrate (CLOACI-I-0115) until interrupted. `--since` cannot be combined with `--follow` (cursor support is future work); use `--since` on a non-follow call for the historical snapshot.

`graph`

Per CLOACI-S-0011, graph is the current inspection noun for computation graphs (graph is the unit of scheduling; a reactor is a specialized trigger node inside it). The reactor noun below survives only for operator manual fire — docs or scripts using reactor as the inspection noun are stale.

Command	HTTP Endpoint	Notes
`graph list`	`GET /v1/health/graphs`	Lists loaded computation graphs with health + reactor pause state.
`graph status <NAME>`	`GET /v1/health/graphs/<name>`	Single graph’s health + accumulators + reactor pause state.
`graph accumulators`	`GET /v1/health/accumulators`	Lists all accumulators across all graphs.

`reactor`

Operator manual-fire actions on reactors loaded in the server’s graph scheduler (CLOACI-T-0751). Typed JSON inputs are serialized to the boundary encoding server-side, so you never hand-craft raw boundary bytes.

Command	HTTP Endpoint	Notes
`reactor force-fire <NAME>`	`POST /v1/health/reactors/<name>/fire`	Fires the reactor with its current cache; no input injected (`mode: force_fire`).
`reactor fire <NAME> --input <SOURCE>=<JSON>`	`POST /v1/health/reactors/<name>/fire`	Replaces the reactor’s cache with typed inputs, then fires (`mode: fire_with`). `--input` is repeatable and required; each is `source=<json>`. The JSON value is parsed as JSON, or treated as a JSON string if it isn’t valid JSON (so `--input note=hello` works unquoted). Full-replace only — no partial merge. Example: `reactor fire pricing_reactor --input prices='{"sym":"ABC","px":12.5}'`.

`accumulator`

Operator manual-inject action on accumulators loaded in the server’s graph scheduler (CLOACI-T-0753) — the front-door analogue of reactor fire. The typed JSON event is serialized to the boundary encoding server-side.

Command	HTTP Endpoint	Notes
`accumulator inject <NAME> --event <JSON>`	`POST /v1/health/accumulators/<name>/inject`	Pushes a single typed event into a running accumulator. `--event` is parsed as JSON, or treated as a JSON string if it isn’t valid JSON (so `--event hello` works unquoted). Example: `accumulator inject orderbook --event '{"sym":"ABC","px":12.5}'`.

`tenant` (admin)

Requires an admin-role key.

Command	HTTP Endpoint	Notes
`tenant create <NAME> [--description <STR>] [--password <PW>]`	`POST /v1/tenants`	Creates a new Postgres schema (per-tenant). `--password` sets the tenant DB password; omitted, the server auto-generates one. The password is never returned — it’s set during provisioning and not surfaced.
`tenant list`	`GET /v1/tenants`	Lists tenant schema names.
`tenant delete <NAME> [--force]`	`DELETE /v1/tenants/<name>`	Triggers the 4-step teardown orchestration (revoke keys → evict runner cache → evict DB cache → drop schema). Each step emits an audit event. The drain step is bounded by `--tenant-deletion-drain-timeout-s` (server flag, default 30s); past that, the runner is hard-evicted. Interactive confirmation unless `--force`. CLOACI-T-0581.

`key`

Command	HTTP Endpoint	Notes
`key create <NAME> [--role <ROLE>]`	`POST /v1/auth/keys`	Roles: `admin`, `write`, `read`. Default `read`. The plaintext key is shown exactly once in table mode (JSON mode returns it in the body with no warning). Save it; it cannot be retrieved later.
`key list`	`GET /v1/auth/keys`	Returns metadata only (ID, name, role, created_at, last_used_at). No hashes, no plaintext.
`key revoke <ID> [--force]`	`DELETE /v1/auth/keys/<id>`	Revokes the key. Confirmation unless `--force`.

The key noun always uses the global /v1/auth/keys surface, which is restricted to platform-admin (god-mode) keys since CLOACI-T-0784. Tenant admins mint tenant-scoped keys via the HTTP API directly (POST /v1/tenants/{tenant}/keys) — there is no cloacinactl verb for that surface today.

`trigger`

Command	HTTP Endpoint	Notes
`trigger list [--limit <N>] [--offset <N>]`	`GET /v1/tenants/<tenant>/triggers?limit=…&offset=…`	Combined cron + custom-poll trigger schedules. Default limit: 100, max 1000 (CLOACI-T-0596 / API-10).
`trigger inspect <NAME>`	`GET /v1/tenants/<tenant>/triggers/<name>`	Single trigger metadata + recent executions.

`secret`

Tenant-scoped encrypted secrets. Requires a tenant admin key, and the server must have CLOACINA_SECRET_KEK set (routes return 503 otherwise). Field values are never passed on argv — each --field/-f names a value source; a literal NAME=value is rejected. Reads never show values. See Manage Secrets.

Command	HTTP Endpoint	Notes
`secret create <NAME> -f <FIELD>…`	`POST /v1/tenants/<tenant>/secrets`	Each `-f`/`--field` (repeatable, required) reads its value from a file (`NAME=@path`), stdin (`NAME=-`, one field only), or an interactive prompt (`NAME` or `NAME=?`). Returns metadata only.
`secret rotate <NAME> -f <FIELD>…`	`PUT /v1/tenants/<tenant>/secrets/<name>`	Replaces the whole field map in place (same `-f` sources as create); the next fire sees the new value.
`secret list`	`GET /v1/tenants/<tenant>/secrets`	Metadata only: names, field names, timestamps. Never values.
`secret get <NAME>`	`GET /v1/tenants/<tenant>/secrets/<name>`	One secret’s metadata. Never values.
`secret delete <NAME> [--force]`	`DELETE /v1/tenants/<tenant>/secrets/<name>`	Interactive confirmation unless `--force`.

Singleton Commands

`status`

cloacinactl status

Composite probe: runs daemon status, server status, and compiler status independently and prints a combined table. Each probe failure is surfaced individually without affecting the others.

`config`

Manage the local config file at ~/.cloacina/config.toml.

`config get <KEY>` / `config set <KEY> <VALUE>` / `config list`

Dotted-path key access. set preserves types: integers stay integers, booleans stay booleans, arrays accept comma-separated values. The config file is created on first set if missing.

Profile management

cloacinactl config profile set <NAME> --api-key <KEY> --server <URL> [--default]
cloacinactl config profile list
cloacinactl config profile use <NAME>
cloacinactl config profile delete <NAME>

Profiles live under [profiles.<name>]. The default_profile field selects which profile is used when --profile is not supplied. See Profile resolution.

`admin`

`admin cleanup-events [--database-url <URL>] [--older-than <DUR>] [--dry-run]`

Deletes execution event records older than the threshold. Duration format: combine d / h / m / s (e.g., 90d, 7d12h, 1d2h30m45s). Case-insensitive. Must be greater than zero. Defaults to 90d.

--dry-run reports what would be deleted without deleting.

`completions`

cloacinactl completions <SHELL>

Emits a shell-completion script to stdout. Supported shells: bash, zsh, fish, powershell. Pipe to your shell’s completion directory or source it from your rcfile.

Configuration File

Located at ~/.cloacina/config.toml (or <home>/config.toml if --home is set). Optional; all fields have defaults. The parser rejects unknown fields (deny_unknown_fields) — but note the load behavior: a file that fails to parse (including one with a single unknown key) is logged as a warning and ignored entirely, falling back to defaults. Because most client commands don’t initialize tracing, the warning is usually invisible — a typo’d config manifests as “no server configured”, not as a parse error.

# Top-level

# Database URL for commands that need it (admin, server start).
database_url = "sqlite:///path/to/cloacina.db"

# Named server-targeting profile selected when --profile is not supplied.
default_profile = "prod"

# Per-profile server-targeting blocks.
[profiles.prod]
server = "https://api.example.com"
api_key = "env:CLOACINA_API_KEY"   # or "raw-key", "file:/path"

[profiles.staging]
server = "https://staging.example.com"
api_key = "file:/etc/cloacina/staging-key"

# Daemon settings.
[daemon]
poll_interval_ms = 500              # Reconciler fallback interval
log_level = "info"                  # NOTE: not currently wired to runtime logging —
                                    # verbosity is controlled by RUST_LOG and `-v`/`--verbose`
shutdown_timeout_s = 30             # Graceful drain timeout
watcher_debounce_ms = 500           # Filesystem watcher debounce
trigger_poll_interval_ms = 1000     # Custom-poll trigger base interval
# cron_max_catchup = 100            # Max cron catchup executions; omit to use
                                    # the runtime default (100)
cron_recovery_interval_s = 300      # Cron recovery sweeper cadence
cron_lost_threshold_min = 10        # Lost-task threshold (present in the schema
                                    # but not currently forwarded to the runner
                                    # config; the runtime default of 10 applies)

# Compiler settings (used by `compiler status` / `compiler health` probes).
[compiler]
local_addr = "127.0.0.1:9000"

# Additional package directories for the daemon (~ expansion supported).
[watch]
directories = ["~/my-workflows", "/opt/cloacina/packages"]

# Server settings read by `cloacinactl server start`.
[server]
default_executor = "default"        # "default" (in-process) or "fleet"

Profile Resolution

Per ADR-0003 §3, server-targeting flags resolve in this order (highest precedence first):

Explicit --server / --api-key flags on the command line.
The named profile from --profile <name>.
The default profile from default_profile.
Error: “no server/key configured.”

Within a profile, the API key is decoded by scheme (raw / env: / file: / keyring:). See API Key Schemes.

File Locations

The ~/.cloacina/ directory (configurable via --home) holds:

~/.cloacina/
├── config.toml              # Configuration file
├── cloacina.db              # SQLite database (daemon mode)
├── bootstrap-key            # Server bootstrap admin key, mode 0600 (server mode)
├── daemon.sock              # Daemon health probe (Unix domain socket)
├── daemon.pid               # Daemon PID file (used by `daemon stop` / `health`)
├── server.pid               # Server PID file
├── compiler.pid             # Compiler PID file
├── packages/                # Default daemon watch directory
│   └── *.cloacina           # Discovered packages
└── logs/
    ├── cloacina.log         # Daemon logs (JSON, daily rotation)
    └── cloacina-server.log  # Server logs (JSON, daily rotation)

CLI Reference

CLI Reference

Synopsis

Global Flags

API Key Schemes

Output Formats

Exit Codes

Environment Variables

Service Commands

daemon

daemon start

daemon stop

daemon status

daemon health

server

server start

Default executor (cloacinactl server start + cloacina-server)

Fleet agent liveness (cloacina-server)

server stop / status / health

compiler

compiler start / stop / status / health

agent

Client Commands

package

package new <NAME> [--lang <LANG>] [--kind <KIND>] [--path <DIR>]

package build <DIR> [--release]

package validate <PATH>

package pack <DIR> [--out <PATH>] [--sign <KEY>]

package publish <DIR> [--release] [--sign <KEY>]

package upload <FILE>

package list [--filter <SUBSTRING>]

package inspect <ID>

package delete <ID> [--force]

constructor

constructor package <CRATE-DIR>

workflow

execution

graph

reactor

accumulator

tenant (admin)

key

trigger

secret

Singleton Commands

status

config

config get <KEY> / config set <KEY> <VALUE> / config list

Profile management

admin

admin cleanup-events [--database-url <URL>] [--older-than <DUR>] [--dry-run]

completions

Configuration File

Profile Resolution

File Locations

See Also

`daemon`

`daemon start`

`daemon stop`

`daemon status`

`daemon health`

`server`

`server start`

Default executor (`cloacinactl server start` + `cloacina-server`)

Fleet agent liveness (`cloacina-server`)

`server stop` / `status` / `health`

`compiler`

`compiler start` / `stop` / `status` / `health`

`agent`

`package`

`package new <NAME> [--lang <LANG>] [--kind <KIND>] [--path <DIR>]`

`package build <DIR> [--release]`

`package validate <PATH>`

`package pack <DIR> [--out <PATH>] [--sign <KEY>]`

`package publish <DIR> [--release] [--sign <KEY>]`

`package upload <FILE>`

`package list [--filter <SUBSTRING>]`

`package inspect <ID>`

`package delete <ID> [--force]`

`constructor`

`constructor package <CRATE-DIR>`

`workflow`

`execution`

`graph`

`reactor`

`accumulator`

`tenant` (admin)

`key`

`trigger`

`secret`

`status`

`config`

`config get <KEY>` / `config set <KEY> <VALUE>` / `config list`

`admin`

`admin cleanup-events [--database-url <URL>] [--older-than <DUR>] [--dry-run]`

`completions`