Skip to content

CLI reference

Generated at build time from the Typer app (horae.cli:app), so it matches the code of this build. horae <command> --help prints the same. Exit codes, the same for every command, are in the runtime reference (see Exit codes).

horae

Horae: a predictable, self-hosted personal agent.

Usage:

horae [OPTIONS] COMMAND [ARGS]...
Option Description
--version Show the version and exit.

horae doctor

Check the instance configuration, pipelines, lockfile, secrets and installed plugins.

Also checks that every path of horae.lock exists, that the instance's own vault/ is the
one horae.lock writes to (instances are not relocatable in v1: a copied or moved
instance is reported), and, with a plugins/ directory, that the plugins are installed
as horae.lock pins them and their commands (interpreters) are executable, every plugin
that is not first-party runs with runtime: container (the plugin host refuses to start
it otherwise), and a local Docker engine is usable when any plugin runs in a container
(nothing is started or pulled). With an llm
step, it also checks that the LLM output validator (a child process) runs.

Warnings (e.g. a cloud model alias without a price, whose usd budget is then
ineffective) are reported but do not fail the check.

Exit codes: 0 no problem (warnings allowed), 1 problems found, 2 usage error, 70 internal
error.
Secret values are never printed. With --json: {schema_version, ok, instance, problems};
an error is {schema_version, error}.

Usage:

horae doctor [OPTIONS]
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--json Print the report as JSON.

horae runs

List runs, newest first, with status, duration and cost.

The runs of live skill evals (`horae eval --live`, pipeline `eval:<skill>`) are listed only
with --all (or --pipeline eval:<skill>).

Exit codes: 0 listed (possibly none), 1 configuration or store problem, 2 usage error,
70 internal error. With --json: {schema_version, instance, runs}; an error is
{schema_version, error}.

Usage:

horae runs [OPTIONS]
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--pipeline, -p Only runs of this pipeline.
--status, -s Only runs with this status.
--limit, -n At most this many runs. Default: 20.
--all Also list live skill evals (pipeline eval:<skill>).
--json Print the runs as JSON.

horae diff

Show what applying a stored run would change, without applying anything.

Notes are read through the instance's plugins (<instance>/plugins, their read-only
`read` operation) when it has them; --vault reads a local vault with the built-in
read-only sink instead. A failed, undone or already applied run is refused.

Exit codes: 0 planned, 1 configuration, plugin or store problem, 2 usage error, 3 unknown
or refused run, 4 planned but some intents cannot be applied, 70 internal error. With
--json, errors are a JSON object on stdout ({schema_version, error: {kind, message}}).

Usage:

horae diff [OPTIONS] {run_id}
Argument Description
run_id The run to show. Required.
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--vault Read notes from this local vault with the built-in read-only sink, instead of through the instance's plugins.
--json Print the diff as JSON.
--color Colour the text diff.

horae replay

Re-execute a recorded run from its inputs and LLM responses, and compare its intents.

Nothing external is called: sources, transforms and the LLM are answered from the record,
and plugins are resolved from horae.lock and the record. The store is opened read-only.

Exit codes: 0 identical; 1 configuration or store problem; 2 usage error (a bad option);
3 unknown run (or no store) or not comparable (pipeline, horae.lock or horae.yaml changed
without --against-current, unresolved plugin, a call the record cannot answer, a record
that is not replayable); 4 different; 70 internal error. With --json the report has every
key, also on errors (outcome `error`, and `error` is {kind, message} like every
command's; `null` otherwise).

Usage:

horae replay [OPTIONS] {run_id}
Argument Description
run_id The run to replay. Required.
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--store SQLite store (default: <state_dir>/horae.db).
--against-current Replay the recorded data through the current pipeline definition, and accept a changed horae.lock or horae.yaml (noted).
--json Print the report as JSON.

horae init

Create a working example instance: the walking skeleton with its plugins installed.

Writes horae.yaml, pipelines/daily-fixture.yaml, horae.lock (the built-in plugins
pinned, file-sink writing to the instance's vault/), state/, plugins/ and .gitignore.
The directory must be new or empty: nothing is ever overwritten, and on a failure
nothing is left behind (the instance is built aside, then moved into place). The
instance is not relocatable: horae.lock and plugins/ hold absolute paths.

Exit codes: 0 created, 1 the files or plugins cannot be written, or a path horae.lock
cannot hold (target_invalid), 2 usage error, 3 the directory is not empty, or not a
directory (a file, a symbolic link), 70 internal error. With --json the result
is {schema_version, instance, vault, pipelines, plugins, files}; an error is
{schema_version, error}.

Usage:

horae init [OPTIONS] [directory]
Argument Description
directory Where to create the instance (new or empty directory). Default: ..
Option Description
--json Print the result as JSON.

horae run

Run a pipeline once through the instance's plugins, and apply its intents.

With --dry-run nothing is applied: the run is recorded (dry run) and the change set it
would apply is shown, as `horae diff` shows it. SIGINT and SIGTERM cancel the run (a
second signal is ignored): before the apply its partial record is saved failed; during
the apply, the apply finishes and the record is saved before the run is reported
interrupted. An llm step calls the backend of its model alias (horae.yaml models), with
the API key from the alias' declared secret. On unchanged input it reuses the cached
output instead (no call, $0); --no-cache skips that lookup. With --llm-replay RECORDINGS the
llm steps are answered from recorded responses found by request digest (no model, no secret;
a request with no recording fails the step, replay_miss).

Exit codes: 0 ok, noop or degraded (dry run: planned without problems), 1 configuration,
plugin, store or runtime problem (the run failed or timed out; a dry run whose plan
could not start a plugin), 2 usage error, 3 unknown pipeline, 4 dry run planned with
problems, 5 pipeline running or apply lock busy, 70 internal error, 130/143 interrupted
by SIGINT/SIGTERM. With --json the result is {schema_version, run_id, run, plan, error};
an error before the run is {schema_version, error}.

Usage:

horae run [OPTIONS] {pipeline}
Argument Description
pipeline The pipeline to run (its file name). Required.
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--dry-run Run without applying anything; show the planned diff.
--var A template variable, KEY=VALUE (repeatable).
--no-cache Call the LLM even on unchanged input (skip the cache lookup; for debugging).
--llm-replay Answer llm steps from recorded responses (a file, or a folder of *.json recordings) instead of calling a model.
--json Print the result as JSON.

horae serve

Run the long-lived Horae process: the built-in scheduler and the HTTP API, until
SIGTERM or SIGINT.

The HTTP API (GET /healthz, GET /runs, GET /runs/<id>; read-only, no authentication of
its own) listens on --host:--port, 127.0.0.1:8080 by default. Never expose it without
the reverse proxy and its SSO middleware. A request whose Host header is not localhost,
127.0.0.1, ::1 or an --allowed-host is refused (400): set the proxy's public hostname.

In builtin mode (horae.yaml scheduler.mode, or HORAE_SCHEDULER=builtin) every pipeline
with a trigger runs at its cron fire times, in its trigger's time zone (else the
instance's), at most scheduler.max_concurrent at once (default 1; the others wait their
turn). Fire times missed while Horae was stopped are not caught up; a fire time while the
pipeline is still running (here or in a manual `horae run`), or more than
scheduler.misfire_grace_s late, is skipped and logged. With HORAE_SCHEDULER=external (or
scheduler.mode: external) no trigger fires: an external scheduler calls `horae run
<pipeline>`. Each run pings its push monitor (scheduler.monitors) up or down; a failed
ping never fails the run. The instance is read once: restart after changing it.

SIGTERM or SIGINT stops it: runs in progress are cancelled and saved, then it exits 0; a
second signal stops waiting for the pings (exit 130/143). Allow it at least 20 s to stop.
Exit codes: 0 stopped, 1 configuration problem (also: the address cannot be bound), 2
usage error, 70 internal error, 130/143 forced by a second SIGINT/SIGTERM.

Usage:

horae serve [OPTIONS]
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--host Address the HTTP API listens on (0.0.0.0 in a container, behind the proxy). Default: 127.0.0.1. Environment: HORAE_HOST.
--port Port of the HTTP API. Default: 8080. Environment: HORAE_PORT.
--allowed-host A Host the HTTP API accepts besides localhost, 127.0.0.1 and ::1: the proxy's public hostname (repeatable; HORAE_ALLOWED_HOSTS: space-separated). Environment: HORAE_ALLOWED_HOSTS.

horae undo

Restore every note a run changed, byte for byte, and mark the run undone.

Notes are restored through the instance's plugins (<instance>/plugins) when it has
them, else (or with --vault) with the built-in local sink on --vault. A note the run
created is removed. Refused when a note changed since the run, or a later run changed it
too, unless --force (the overwritten bytes are kept in the journal); always refused when
the sink is another vault than the run's. A task status change (a tick, a snooze) is put
back through the sink that made it, with the task index; a task edited since is refused
unless --force. Created tasks, notifications and HTTP calls cannot be undone: they are
listed. Undo is not a transaction: when it stops half-way, the report says what was
restored (it stays restored) and what was not, and running it again after an
interruption continues where it stopped.

Exit codes: 0 undone, 1 configuration, store, plugin or sink problem (or another vault),
2 usage error, 3 unknown, running or dry run (or nothing to undo), 4 refused (a note
changed since the run, or by a later run), 5 pipeline running or apply lock busy, 70
internal error. With --json, errors are a JSON object on stdout ({schema_version,
error}).

Usage:

horae undo [OPTIONS] {run_id}
Argument Description
run_id The run to undo. Required.
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--vault Restore notes in this local vault with the built-in local sink, instead of through the instance's plugins.
--force Restore notes and tasks that changed since the run too (your explicit choice).
--json Print the report as JSON.

horae usage

Show what LLM calls cost, per pipeline and day, with totals.

From the usage ledger: one row per LLM call, days in the instance's time zone (as when
each call was made). Flags: (*) calls of a model alias without a price, (+) calls in
flight, (~) calls settled at the most they could cost, (!) calls that cost more than
reserved. By model, a call that reached no provider has a null backend and model, and
its alias.

Exit codes: 0 listed (possibly nothing), 1 configuration or store problem, 2 usage error,
70 internal error. With --json: {schema_version, instance, by, pipeline, since, until,
rows, total}; an error is {schema_version, error}.

Usage:

horae usage [OPTIONS]
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--pipeline, -p Only calls of this pipeline.
--since From this local day (YYYY-MM-DD), inclusive.
--until Up to this local day (YYYY-MM-DD), inclusive.
--by Group by day, pipeline or model (default: day and pipeline).
--json Print the report as JSON.

horae eval

Run a skill's golden cases (skills/<ns>/<skill>/evals/<case>.yaml).

Offline (default): each recorded response (evals/recorded/<backend>/<case>.json) goes
through the real backend's request rendering, the output validator, the intent check and
the action guard, and is compared with the case's expectations (unified diffs). No
network, no secret. A recording older than the skill, prompt, input or schema is reported
stale.

--live sends each case once through --alias (costs money): the worst case is shown and
must fit --max-usd and the instance's daily budget (--max-usd is required without a
daily usd ceiling; a cloud alias without a price needs --allow-unpriced), then --yes or a
terminal confirmation is needed. The spend is recorded in the usage ledger, as a run of
pipeline eval:<skill> (horae runs --all lists it). A report is written to
<state_dir>/evals/<namespace>/<skill>/. --record (with --plugin-dir) replaces the
recordings of the cases whose live answer passes (redacted).

Exit codes: 0 every case passed, 1 problems (configuration, plugin, skill or eval files;
a case that could not be evaluated; a report not written), 2 usage error, 3 unknown
skill, case or alias, or a live eval refused (over budget, unpriced, not confirmed, busy),
4 some case failed, 70 internal error, 130 interrupted. With --json: {schema_version,
mode, skill, skill_version, skill_digest, plugin, alias, run, cases, summary, estimate,
report, report_error, error}; an error is {schema_version, error}.

Usage:

horae eval [OPTIONS] {skill}
Argument Description
skill The skill, <namespace>/<skill>. Required.
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--plugin-dir A plugin folder, or a folder of plugins, instead of the instance's plugins.
--case Only this case.
--alias The instance's model alias to render with.
--live Send each case to the model (costs money).
--record With --live and --plugin-dir: replace the recordings of the passing cases.
--yes With --live: do not ask before sending.
--max-usd With --live: refuse when the worst case costs more.
--allow-unpriced With --live: send through a cloud alias without a price.
--timeout Seconds per case (validation included). Default: 60.0.
--json Print the report as JSON.

horae approval

Approve, deny or revoke what an MCP client asked to run (pipeline.run).

Usage:

horae approval [OPTIONS] COMMAND [ARGS]...

horae approval list

List pipeline.run approvals, newest first (expired ones are recorded first).

Exit codes: 0 listed, 1 configuration or store problem, 2 usage error, 70 internal
error.

Usage:

horae approval list [OPTIONS]
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--status Only approvals with this status.
--json Print the result as JSON.

horae approval show

Show one approval and its journal of transitions.

Exit codes: 0 shown, 1 configuration or store problem, 3 unknown approval, 70 internal
error.

Usage:

horae approval show [OPTIONS] {approval_id}
Argument Description
approval_id The approval id (apr-...). Required.
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--json Print the result as JSON.

horae approval approve

Review and apply what an MCP client asked to run, on this terminal.

Re-plans the dry run, refuses if anything changed since (the plan, the pipeline, its
configuration, the vault), shows every change in full and asks you to retype a short
code. Needs an interactive terminal; there is no --yes. This is friction against
approving by accident, not a barrier against an agent with a shell as you. Applied once,
as a new run (`horae undo <run>` reverts it).

Exit codes: 0 applied, 1 not pending, not interactive, not confirmed, not reviewable or
the apply failed,
3 unknown approval, 4 plan mismatch (nothing applied), 5 pipeline running or apply lock
busy, 70 internal error, 130/143 interrupted.

Usage:

horae approval approve [OPTIONS] {approval_id}
Argument Description
approval_id The approval id (apr-...). Required.
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.

horae approval deny

Deny a pending approval: nothing is applied.

Exit codes: 0 denied, 1 not pending or store problem, 3 unknown approval, 70 internal
error.

Usage:

horae approval deny [OPTIONS] {approval_id}
Argument Description
approval_id The approval id (apr-...). Required.
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--json Print the result as JSON.

horae approval revoke

Revoke every pending approval (--all): nothing of them is applied.

Exit codes: 0 done, 1 store problem, 2 usage error (no --all), 70 internal error.

Usage:

horae approval revoke [OPTIONS]
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--all Revoke every pending approval.
--json Print the result as JSON.

horae cache

Manage the LLM cache (accepted outputs reused on unchanged input).

Usage:

horae cache [OPTIONS] COMMAND [ARGS]...

horae cache purge

Delete LLM cache entries: all of them, or older ones, optionally of one skill.

The next run on an input whose entry was deleted calls the model again. The store is
never created; nothing is locked.

Exit codes: 0 purged (possibly nothing), 1 configuration or store problem, 2 usage error
(nothing selected, --all with --older-than), 70 internal error. With --json:
{schema_version, instance, all, older_than_days, skill, deleted, remaining}; an error is
{schema_version, error}.

Usage:

horae cache purge [OPTIONS]
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--all Delete every entry.
--older-than Delete the entries created more than DAYS days ago.
--skill Only this skill's entries (e.g. pack/brief).
--json Print the result as JSON.

horae mcp

Horae as an MCP server for other agents (read tools, approval-gated pipeline.run).

Usage:

horae mcp [OPTIONS] COMMAND [ARGS]...

horae mcp serve

Serve the read-only tools tasks.today, brief.latest and runs.recent, and pipeline.run.

Over stdio by default, for an MCP client to start (Claude Code: claude mcp add horae --
horae mcp serve -i <instance>); no port, no token. With --http, streamable HTTP at
http://127.0.0.1:8765/mcp where every request needs a token from `horae mcp token
create` (Authorization: Bearer hmcp_...); it refuses to start without a usable token.
The read tools change nothing (over HTTP, only a token's last use is recorded). Task
titles, note paths and errors they return are untrusted text. pipeline.run (scope
pipeline.run) makes a dry run only and returns an approval id that expires after
--approval-ttl minutes; you approve it with `horae approval approve <id>`.

Exit codes: 0 stopped, 1 configuration problem (no usable token, port in use), 2 usage
error, 70 internal error.

Usage:

horae mcp serve [OPTIONS]
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--brief-pipeline The pipeline brief.latest reports (the daily brief). Default: daily-brief.
--http Serve streamable HTTP with bearer tokens instead of stdio.
--host With --http: the address to listen on (loopback). Default: 127.0.0.1.
--port With --http: the port (0: any free one). Default: 8765.
--allowed-host With --http: a Host header to accept besides loopback names (repeatable).
--approval-ttl Minutes a pipeline.run approval stays valid. Default: 15.

horae mcp token

Manage the bearer tokens of `horae mcp serve --http`.

Usage:

horae mcp token [OPTIONS] COMMAND [ARGS]...
horae mcp token create
Create a bearer token for `horae mcp serve --http` and print it once.

Only its SHA-256 digest is stored: copy the token now, it cannot be shown again. A name
is unique among the tokens not revoked.

Exit codes: 0 created, 1 configuration or store problem, 2 usage error, 3 name in use,
70 internal error.

Usage:

horae mcp token create [OPTIONS] {name}
Argument Description
name A name for the token (e.g. laptop-claude). Required.
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--scope A scope to grant (repeatable): read (default) or pipeline.run (#55).
--expires-in Expire the token after DAYS days (default: never).
--json Print the result as JSON.
horae mcp token list
List the MCP tokens (revoked ones too) with their status; never a token.

Exit codes: 0 listed, 1 configuration or store problem, 70 internal error.

Usage:

horae mcp token list [OPTIONS]
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--json Print the result as JSON.
horae mcp token revoke
Revoke an MCP token: the server refuses it from its next request on.

Exit codes: 0 revoked, 1 configuration or store problem, 2 usage error, 3 no unrevoked
token has that name, 70 internal error.

Usage:

horae mcp token revoke [OPTIONS] {name}
Argument Description
name The name of the token to revoke. Required.
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--json Print the result as JSON.

horae plugin

Find and install plugins from the configured marketplaces.

Usage:

horae plugin [OPTIONS] COMMAND [ARGS]...

horae plugin resolve

Resolve a plugin name (and version) to its repository and pinned commit.

Marketplaces are searched in the order of `marketplaces` in horae.yaml. Without a version
the highest semantic version wins (pre-releases only with --pre). A name that two
marketplaces list under different repositories is an error naming both: pick one with
`marketplace_pins` in horae.yaml.

Exit codes: 0 resolved, 1 configuration problem or an unreachable marketplace without
cache, 2 malformed reference, 3 unknown plugin or version, or a conflict, 70 internal.

Usage:

horae plugin resolve [OPTIONS] {NAME[@VERSION]}
Argument Description
NAME[@VERSION] Plugin to resolve. Required.
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--offline Do not fetch: use the cached copy of every marketplace.
--pre Also consider pre-releases when no version is named.
--json Print the result as JSON.

horae plugin add

Install a plugin at the commit its marketplace pins, approve its permissions, and pin
it in horae.lock.

The name is resolved as `horae plugin resolve` does. A plugin that is not first-party (a
community tier, an index you added, or a direct install) installs only when horae.yaml runs
it in a container: `plugins.<name>.runtime: container` or `plugin_defaults.runtime:
container`, with Docker available. The repository is cloned over https and the pinned
commit checked out; the install is refused when the tag v<version> and the pinned commit
disagree, or when plugin.yaml is
invalid or names another plugin or version. The permissions plugin.yaml asks for are then
shown and must be approved: interactively, or with --yes when horae.lock already approves
exactly this version, commit and permissions (without a terminal and without --yes, the
install is refused). --allow-host and --allow-local add grants beyond the manifest (written
to horae.lock; give them again with --yes). Nothing is half-installed. Once approved, its
dependencies are installed in its own venv.

A direct install, https://HOST/OWNER/REPO@SHA with the full commit SHA (no tag, branch or
short SHA; no credentials, http, ssh or file URL), reads no marketplace (so --pre and
--offline do not apply) and, having no tier, needs runtime: container too.

Exit codes: 0 installed and approved, 1 configuration problem, unreachable marketplace
without cache, a repository that cannot be fetched, or an invalid horae.lock, 2 malformed
reference or grant, 3 unknown plugin or version, a conflict, a refused install (tier,
verification, approval) or a plugin already installed, 5 horae.lock is being written by
another command, 70 internal.

Usage:

horae plugin add [OPTIONS] {NAME[@VERSION] | URL@SHA}
Argument Description
NAME[@VERSION] | URL@SHA Plugin to install: a marketplace name, or an https git URL pinned to a full commit SHA (a direct install, only with runtime: container). Required.
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--offline Do not fetch: use the cached copy of every marketplace.
--pre Also consider pre-releases when no version is named.
--yes, -y Approve without asking, only when horae.lock already has an entry for this exact version and commit with identical permissions (a reproducible re-install).
--allow-host Also grant this https host (repeatable), beyond what the plugin declares.
--allow-local Also grant this local-network endpoint (repeatable; plain http allowed), e.g. 192.168.1.10:8123.
--json Print the result as JSON.
List the plugins of the configured marketplaces, by priority, with their versions.

Exit codes: 0 listed (possibly nothing), 1 configuration problem or an unreachable
marketplace without cache, 70 internal.

Usage:

horae plugin search [OPTIONS] [query]
Argument Description
query Part of a plugin name (default: all).
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--offline Do not fetch: use the cached copy of every marketplace.
--json Print the result as JSON.

horae plugin upgrade

Upgrade an installed plugin, showing the permission diff and asking again for anything new.

The version is resolved as `horae plugin add` does (highest release, --pre, or NAME@VERSION;
the install gate of `add`). The new version is installed beside the old one with its own
venv; what it asks for is compared with horae.lock: a new host, local endpoint, secret,
intent, path or pack pipeline (or a changed one, or a dropped personal field) must be
approved again. Hosts you added before are kept. Only after approval and a complete install
are the trees swapped and horae.lock rewritten; on any failure the old version and the lock
are left as they were. A lower version is refused without --allow-downgrade.

A direct install is upgraded with URL@SHA: the same repository URL as in horae.lock and the
full SHA of a commit its branches or tags reach. A plugin that is not first-party (a
community tier, an index you added, a direct install) is refused unless horae.yaml runs it
with runtime: container.

Exit codes: 0 upgraded or already current, 1 configuration problem, unreachable marketplace
or repository, or an invalid or unwritable horae.lock, 2 malformed reference or grant, 3
not installed, refused (tier, downgrade, verification, approval), 5 horae.lock is being
written by another command, 70 internal.

Usage:

horae plugin upgrade [OPTIONS] {NAME[@VERSION] | URL@SHA}
Argument Description
NAME[@VERSION] | URL@SHA Installed plugin to upgrade, or for a direct install the new commit of its repository (an https git URL pinned to a full commit SHA). Required.
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--offline Do not fetch: use the cached copy of every marketplace.
--pre Also consider pre-releases when no version is named.
--yes, -y Approve without asking, only when nothing widens (no new host, secret, intent, path or pipeline) or horae.lock already approves the target.
--allow-host Also grant this https host.
--allow-local Also grant this local-network endpoint.
--allow-downgrade Allow installing a lower version.
--json Print the result as JSON.

horae plugin remove

Remove an installed plugin: its tree and venv, its pack pipelines, its horae.lock entry.

Refused while the plugin is listed under plugins: in horae.yaml (disable it first). Only
the pipelines it installed that still have their approved digest are deleted; a file you
changed or added is kept. Its secrets are kept unless --delete-secrets (then only files of
the secrets directory that no other plugin, model or monitor uses); the files it wrote and
the run history are always kept. What was kept is listed.

Exit codes: 0 removed, 1 configuration problem or an invalid or unwritable horae.lock, 2
malformed name, 3 not installed by `horae plugin add`, or enabled, 5 horae.lock is being
written by another command, 70 internal.

Usage:

horae plugin remove [OPTIONS] {NAME}
Argument Description
NAME Installed plugin to remove. Required.
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--delete-secrets Also delete the plugin's secret files that nothing else uses.
--json Print the result as JSON.

horae plugin audit

List the installed plugins and check them against horae.lock.

For each plugin of horae.lock or plugins/: its version, source (marketplace, direct, or
local for a built-in or hand-copied one), tier, whether it is enabled in horae.yaml, the
permissions horae.lock grants it, its pipelines and its last activity (the latest stored run
that used it). Drift is reported: a locked plugin not installed or installed but not
locked, an install record or manifest that is not the locked one, a missing venv, a pack
pipeline missing, changed or not approved, a plugin that is not first-party but does not
run with runtime: container (the host refuses to start it), and what an interrupted upgrade
or remove left.

Exit codes: 0 no drift, 1 configuration problem or an invalid horae.lock, 4 drift found,
70 internal.

Usage:

horae plugin audit [OPTIONS]
Option Description
--instance, -i Instance directory (holds horae.yaml). Default: .. Environment: HORAE_INSTANCE.
--json Print the result as JSON.