CLI reference

CLI reference

Every holaryn subcommand, with its flags and a short example. Run holaryn --help or holaryn <command> --help for the same information in the terminal, and holaryn --version to print the installed version.

Many commands accept --state-dir <path> to point at a specific state directory (see Running the agent). Commands that talk to a running host (question, steer, resume, coding-jobs, team, peer) also accept --host, --port, and --auth-token; when omitted, the host and port are discovered from the running host's status file, and --auth-token must match the token the host was started with, if any.

holaryn run

Run an attended agent session in the terminal.

holaryn run [task] [--autonomy POSTURE] [--allow-all {yes,no}] [--unrestricted {yes,no}]
          [--policy FILE] [--model ID] [--scope SCOPE] [--profile NAME] [--dry-run]

holaryn run --autonomy selective "Clean up the downloads folder"

holaryn serve

Run the persistent Holaryn host (scheduler, web UI, subagents, teams, peers).

holaryn serve [--no-web] [--web] [--web-view] [--web-view-binary PATH] [--host HOST]
            [--port PORT] [--auth-token TOKEN | --auth-token-file FILE]
            [--allowed-host HOST ...] [--state-dir DIR] [--log-level LEVEL]

holaryn serve --state-dir D:\holaryn-state --port 9000

For non-loopback deployments, authentication is mandatory. Prefer --auth-token-file so the token
does not enter process arguments, and permit only the exact proxy hostnames.

holaryn deployment

Inspect, diagnose, back up, verify, and restore a self-host deployment. Status and support bundles
exclude configuration values. Backup requires a stopped host and reads recovery material only from
an explicitly named environment variable.

holaryn deployment [--state-dir DIR]
  status
  support-bundle OUTPUT [--secret-canary-env NAME ...]
  backup OUTPUT --password-env NAME
  verify-backup ARCHIVE --password-env NAME
  restore-backup ARCHIVE DESTINATION --password-env NAME

• status prints installed/image version metadata, safe host fields, encryption and migration
  state, storage counts, and configuration field/source shape.
• support-bundle writes bounded redacted log tails plus the safe status contract. Extra canary
  variables make post-write redaction validation fail closed if a known value remains.
• backup checkpoints SQLite and writes an authenticated encrypted archive of every durable
  regular state file while holding the stopped-host lock.
• verify-backup authenticates every archive entry.
• restore-backup writes only to a new empty destination and rejects transient deployment state.

export HOLARYN_BACKUP_PASSWORD
holaryn deployment --state-dir /var/lib/holaryn status
holaryn deployment --state-dir /var/lib/holaryn backup ./state.sxdeploy \
  --password-env HOLARYN_BACKUP_PASSWORD
holaryn deployment verify-backup ./state.sxdeploy \
  --password-env HOLARYN_BACKUP_PASSWORD
holaryn deployment restore-backup ./state.sxdeploy ./restored-state \
  --password-env HOLARYN_BACKUP_PASSWORD

See Self-host with Docker Compose for the stopped-service sequence,
off-host retention, update, and rollback procedure.

holaryn browser

Inspect or repair the bundled Chromium runtime, run the deterministic local demo, and export a
session trace. No Node.js, npx, MCP configuration, or application restart is required.

holaryn browser [--state-dir DIR]
  status [--json]
  demo
  repair
  trace SESSION_ID [--output FILE]

• status reports whether the matching driver and Chromium executable are installed and verifies
  their hashes.
• demo launches an isolated local page, exercises semantic browser automation, prints the
  session/result/trace path, and exits.
• repair deterministically reinstalls the matching Chromium runtime without deleting profiles.
• trace exports the redacted action record for a known session.

See Browser agent for profiles, approvals, downloads, recovery, and the
keyboard-accessible supervision surface.

holaryn computer

Inspect the native adapter, run the deterministic Windows UIA demo, or export a redacted trace.

holaryn computer [--state-dir DIR]
  status [--json]
  demo
  trace SESSION_ID [--output FILE]

• status reports platform availability, the adapter name, visual-fallback policy, and known
  application sessions.
• demo opens Notepad and Calculator, enters text and verifies 1 + 2 = 3 through semantic UIA
  controls, reports trace paths, and closes both applications.
• trace exports the durable redacted action record for a known session.

Windows on the ordinary interactive desktop is supported in this release. See
Native computer use for application limits, privacy, approvals, and emergency
takeover.

holaryn onboard

Start or resume the privacy-safe first-success path shared with the desktop UI.

holaryn onboard [--state-dir DIR] [--json]
              [status | start | configure | roles | posture {ask,selective} |
               verify | demo | undo-demo | complete | reset]

• status (also the default) prints progress, diagnostics, a repair command, and the next step. --json emits the typed non-secret status contract.
• configure [--preset ID] [--connection-id ID] [--model MODEL] [--base-url URL] selects from the provider catalog, asks for required keys with hidden input, scans models, and sets the selected model as default. Credentials are never accepted as command-line arguments.
• roles accepts the recommended general/coding/vision/embedding assignments.
• posture {ask,selective} records a conservative attended starting posture.
• verify [--model ID] streams a fixed tool-free prompt through the production provider.
• demo previews a generated-sandbox write_file call and waits for explicit approval; undo-demo removes only the known generated file.
• complete requires both a successful response and successful tool milestone. reset clears progress without deleting provider settings.

Place --state-dir and --json before the subcommand. See First-success onboarding for the complete flow and recorded-data contract.

holaryn capabilities

Show the installed version, release channel, and the public capabilities verified for this build.

holaryn capabilities [--json] [--maturity {stable,beta,experimental,planned}]

• --json prints the complete versioned registry with ownership, surfaces, platforms, prerequisites, network/privacy/approval implications, limitations, documentation, and verification evidence.
• --maturity filters the listed capabilities without changing the manifest schema or installed-version diagnostics.

The same data drives Settings → About and the living capability matrix.

holaryn api-key

Create, inspect, rotate, or revoke credentials for the supported public automation API. Credential
values are printed only by create and rotate; list returns metadata only.

holaryn api-key [--state-dir DIR] create --name NAME --organization ORG \
  --project PROJECT [--project PROJECT] [--scope SCOPE] [--expires-in SECONDS]
holaryn api-key [--state-dir DIR] list
holaryn api-key [--state-dir DIR] rotate KEY_ID
holaryn api-key [--state-dir DIR] revoke KEY_ID

Omitting --scope grants the ordinary service scopes but not admin:read or admin:write.
Repeat --scope to construct a narrower or explicitly administrative credential. See the
public API deployment and SDK guide before enabling a remote listener.

holaryn local-model

Manage local hardware fit, model provenance and storage, Ollama/llama.cpp
endpoints, routing roles, and fixed smoke benchmarks.

holaryn local-model {status,diagnostics,runtimes,hardware,catalog,import,add-ollama,
                   download,adopt,scan,start,health,stop,restart,benchmark,
                   register,role,remove} [options]

Read-only commands (status, diagnostics, runtimes, hardware, and
catalog) make no catalog or provider request. Network access occurs only for an
explicit download or endpoint action. Mutating commands accept --state-dir;
every command supports --json.

holaryn local-model catalog --fit
holaryn local-model add-ollama qwen2.5:7b --id local-qwen
holaryn local-model adopt ollama http://127.0.0.1:11434/v1 --id ollama-local
holaryn local-model register ollama-local local-qwen
holaryn local-model role general local-qwen
holaryn local-model benchmark ollama-local

See Local models for verified download/import examples,
ownership boundaries, supervision behavior, fit assumptions, privacy, and repair
steps.

holaryn instructions

Explain the exact repository guidance that applies to one or more target paths. This is a local,
read-only command; it does not start a model or execute validation commands.

holaryn instructions WORKSPACE [TARGET ...] [--json]

With no target, Holaryn explains root guidance. Text output includes each applicable source's scope,
trust, SHA-256 hash, precedence, target set, mode, priority, required validation, truncation/conflict
state, and resolved content. --json emits the same typed evidence with the resolution snapshot
hash. Targets and instruction symlinks cannot escape the canonical workspace root.

holaryn instructions D:\projects\example src\app.py
holaryn instructions D:\projects\example src\app.py --json

See Repository instructions for compatible
filenames, optional frontmatter, precedence, invalidation, and safety behavior.

holaryn worktree

Create, inspect, validate, integrate, archive, recover, and safely clean durable coding worktrees.
Commands print structured JSON. An identifier can be a worktree_id or its bound Code/coding-job
session id.

holaryn worktree [--state-dir DIR] SUBCOMMAND

Common flow:

holaryn worktree create D:\projects\example --mode isolated
holaryn worktree compare wt_1234abcd
holaryn worktree validate wt_1234abcd --commands-json "[[\"uv\",\"run\",\"pytest\"]]"
holaryn worktree integrate wt_1234abcd adopt --plan-sha256 PLAN --target-revision TARGET --approve
holaryn worktree cleanup wt_1234abcd

Subcommands are create, list, status, compare, validate, integrate, rebase,
archive, recover, cleanup, and abandon. Integration strategies are adopt (fast-forward),
apply (cherry-pick), and merge. Starting a rebase or integration requires the exact digest and
target revision from the reviewed comparison plus --approve. create --root ALIAS=PATH adds an
explicit secondary repository mapping. See Isolated coding worktrees for
the safety and recovery contract.

holaryn schedule

Manage scheduled agent runs. The positional arguments are either list, cancel <job-id>, or a schedule spec followed by the prompt to run.

holaryn schedule [--state-dir DIR] [--posture POSTURE] [--on-gated {cancel,hold}]
               [--misfire {skip,fire-once}] [--policy FILE] [--profile NAME]
               [--team NAME] [--to MEMBER] [--topic TOPIC]
               (list | cancel JOB_ID | SPEC PROMPT...)

The spec is cron:…, interval:…, date:…, or a natural-language phrase such as "every weekday at 8" (resolved by your configured model).

holaryn schedule "cron:0 8 * * 1-5" Summarize yesterday's inbox
holaryn schedule list
holaryn schedule cancel 3f2a…

holaryn workflow

Author, review, publish, run, and supervise immutable declarative workflows in the selected state
directory.

holaryn workflow [--state-dir DIR]
  list
  show WORKFLOW_ID VERSION [--format {yaml,json}]
  validate PATH
  import PATH
  approve-import WORKFLOW_ID VERSION
  publish WORKFLOW_ID VERSION
  deprecate WORKFLOW_ID VERSION
  run WORKFLOW_ID [--version VERSION] [--inputs JSON_OR_@PATH]
                  [--idempotency-key KEY]
  instances [--workflow-id WORKFLOW_ID]
  cancel INSTANCE_ID [--reason TEXT]

validate is a no-action dry-run. import stores an untrusted disabled draft and prints
permission, dependency, secret, trigger, network, risk, and consequence changes. Record the review
with approve-import before publishing. A run is queued durably; keep the desktop app,
holaryn serve, or the OS service running to execute it.

holaryn workflow validate ./research-brief.yaml
holaryn workflow run research-brief --version 1.0.0 --inputs '{"topic":"local AI"}'
holaryn workflow instances --workflow-id research-brief

See Workflows and reusable runbooks.

holaryn status

Show the persistent host's status: whether it is running, where, plus pending approvals, questions, resumable runs, and jobs.

holaryn status [--state-dir DIR]

holaryn status

holaryn question

List or answer parked operator questions from running or unattended sessions.

holaryn question [--state-dir DIR] [--host HOST] [--port PORT] [--auth-token TOKEN]
               (list | answer QUESTION_ID ANSWER...)

The answer is posted to the running host so the paused run resumes with your text.

holaryn question list
holaryn question answer q-42 "Use README.md"

holaryn steer

Queue a live steering directive for a running session. It is appended to the run's transcript at the next turn boundary and never interrupts a tool call already executing.

holaryn steer [--state-dir DIR] [--host HOST] [--port PORT] [--auth-token TOKEN]
            [SESSION-ID] DIRECTIVE

If the session id is omitted, the directive targets the lead web session.

holaryn steer "Prioritize the failing tests"
holaryn steer web/sub:1 "Stop and report what you have"

holaryn resume

List or decide restart resume actions — side-effectful tool calls whose outcome is unknown after a host restart.

holaryn resume [--state-dir DIR] [--host HOST] [--port PORT] [--auth-token TOKEN]
             (list | decide DECISION_ID {rerun,skip,abort})

holaryn resume list
holaryn resume decide d-7 skip

holaryn coding-jobs

List, steer, or cancel background coding jobs (delegated coding-CLI runs). steer sends a mid-run instruction to a running claude-code job; codex jobs cannot be steered (cancel and resume via the child session id instead).

holaryn coding-jobs [--state-dir DIR] [--host HOST] [--port PORT] [--auth-token TOKEN]
                  (list | steer JOB_ID MESSAGE | cancel JOB_ID)

holaryn coding-jobs list
holaryn coding-jobs steer cj_1234abcd "skip the refactor, just fix the failing test"

holaryn team

Manage agent teams — linked local agents, coding CLIs, and remote peers that collaborate on a shared board. See Teams.

holaryn team [--state-dir DIR] [--host HOST] [--port PORT] [--auth-token TOKEN] SUBCOMMAND

• create <name> [--topic-budget N] [--ask-timeout SECONDS] — create a team.
• add <team> <member> [--profile NAME] [--backend {claude-code,codex}] [--workspace DIR] [--permission {safe,edits}] [--peer NAME] — add a member. --backend makes it a coding-CLI member; --peer bridges to a paired peer host.
• remove <team> <member> — remove one member: stops its worker and cancels its pending questions with a note on the thread. Prefers the running host; works offline too.
• status [name] — show all teams, or one team.
• post <team> [--to MEMBER] [--topic TOPIC] <text…> — post a message; an empty --to broadcasts.
• archive <name> — archive a team.

holaryn team create research
holaryn team add research coder --backend claude-code --workspace ./repo
holaryn team post research --to coder Investigate the flaky test

holaryn peer

Manage paired peer machines — other Holaryn hosts you can message and delegate to. See Peers and networking.

holaryn peer [--state-dir DIR] [--host HOST] [--port PORT] [--auth-token TOKEN] SUBCOMMAND

• add <name> --url URL --token TOKEN [--node-id ID] — pair a peer manually with its base URL and inbound peer token.
• remove <name> — unpair a peer.
• list — list paired peers.
• discovered — list Holaryn instances discovered on the local network.
• pair <node_id> — pair with a discovered instance in one step (tokens exchanged).
• enable <name> / disable <name> — switch a paired peer's connection on or off (disable blocks both directions but keeps the entry).
• targets <peer> — list a peer's addressable @-targets.
• token set <value> / token clear — manage this host's inbound peer token.
• send <peer> <text…> — message a peer's agent.
• ask <peer> <text…> — ask a peer's agent and wait for the answer.

holaryn peer discovered
holaryn peer pair 4c9d…
holaryn peer ask studio "Is the render job finished?"

holaryn device

Inspect and control narrow capabilities advertised by a paired mobile or edge device. See
Device capability nodes.

holaryn device [--state-dir DIR] SUBCOMMAND

• list [--json] — list nodes, presence, OS permissions, availability, and server grants.
• activity [--device-id ID] [--limit N] [--json] — inspect bounded device activity.
• grant <device-id> <capability> <ask|allow|deny> [--expires-in SECONDS] — change the
  independent server grant.
• invoke <device-id> <capability> [--parameters JSON] [--expected-upload-bytes N] [--ttl N] —
  queue an exact, expiring request.
• cancel <invocation-id> — cancel queued or running device work.
• revoke <device-id> [--lost] — revoke the node and shared mobile credential.
• wipe <device-id> — ask the online PWA to remove local credentials and capability state.

holaryn device list
holaryn device grant phone_… notification.send allow
holaryn device invoke phone_… notification.send --parameters '{"title":"Ready"}'

holaryn service

Manage the Holaryn host as a native OS service (systemd, launchd, or Windows SCM). See Running the agent for platform specifics.

holaryn service install [--state-dir DIR] [--host HOST] [--port PORT] [--env-file FILE]
                      [--service-name NAME] [--executable PATH]
                      [--platform {linux,darwin,windows}] [--print-artifact]
holaryn service (uninstall | status | start | stop) [--service-name NAME]
                      [--platform {linux,darwin,windows}]

status additionally accepts --state-dir to read host details from a specific state directory.

sudo holaryn service install --platform linux --state-dir /var/lib/holaryn --env-file /etc/holaryn/holaryn.env
holaryn service status

holaryn install-cli / holaryn uninstall-cli

Windows only: install or remove the frozen holaryn CLI on the per-user PATH (used by the desktop app's bundled CLI).

holaryn install-cli [--source DIR] [--root DIR]
holaryn uninstall-cli [--root DIR]

• --source DIR — path to the frozen onedir (contains holaryn.exe and _internal); defaults to the running frozen binary's own folder.
• --root DIR — install root (default %USERPROFILE%\.holaryn-agent).

holaryn mcp

Manage MCP servers — external tools connected over the Model Context Protocol. All subcommands accept --manifest <path> to use a specific manifest file. See Tools and MCP.

• list — list configured servers.
• inspect <server> — connect to one server and list its tools, their approval gating, and behavior hints.
• remove <server> — remove a server.
• add <server> --transport {stdio,http,sse} [options] — add or replace a server:

holaryn mcp add github --transport stdio --command gh-mcp --trusted
holaryn mcp inspect github

holaryn skill

Manage installed skills. All subcommands accept --root <dir> for the managed skill root (default ~/.holaryn/skills). See Skills.

• list — list discovered skills with source and trust state.
• inspect <skill_id> — show one skill's details and provenance.
• install <source> [--yes] [--overwrite] — install from a local folder or a git URL (confirmation prompt unless --yes).
• remove <skill_id> [--yes] — delete an installed skill.
• search [query…] [--index-url URL] — search the curated skill index; an empty query browses everything. --index-url accepts an https URL, a file:// URL, or a local path.
• enable <skill_id> / disable <skill_id> — show or hide a skill for new sessions.
• trust <skill_id> / untrust <skill_id> — let the skill's scripts run with notification instead of ask-first, or revert that.

holaryn skill search calendar
holaryn skill install https://github.com/example/skill-pack
holaryn skill trust example/meeting-notes

holaryn plugin

Manage installed plugins (bundles of skills, MCP servers, and schedule templates). Plugins install disabled and must be reviewed and enabled before new sessions load them.

• list — list installed plugins with version, state, and origin.
• inspect <name> — show one plugin's manifest details.
• install <source> [--yes] [--overwrite] — install from a local folder or a git URL.
• update <name> [--yes] — reinstall from the recorded source; the plugin is disabled again pending review.
• remove <name> [--yes] — delete an installed plugin.
• enable <name> [--yes] — review the plugin's MCP processes/connections and let new sessions load it.
• disable <name> — hide the plugin from new sessions.

holaryn plugin install ./my-plugin
holaryn plugin enable my-plugin

holaryn marketplace

Inspect and manage signed, immutable capability packages across configured public/private
registries, mirrors, and offline files. See Trusted marketplace.

• status — show remote rollout, locked policy, cached registries, and installed package counts.
• refresh <registry_id> <location> — verify and cache one allowed signed registry index.
• search [query] [--kind KIND] [--tier TIER] [--category CATEGORY] [--quality QUALITY] [--compatible] — browse or filter cached catalogs with an explainable rank.
• inspect <package_id> [--version VERSION] — show provenance, compatibility, permissions, data access, review/tests, digests, and advisories.
• install <package_id> [--version VERSION] [--activate] [--yes] — download, verify, and stage an immutable catalog version.
• update <package_id> [--version VERSION] [--activate] [--yes] — stage a newer signed version of an already-installed package without moving its active pointer.
• verify <archive> — verify a signed offline archive without changing state.
• import <archive> [--activate] [--yes] — policy-check and stage a signed offline archive.
• activate <package_id> <version> [--yes] — perform the exact-version trust/permission review and atomically activate.
• rollback <package_id> [--yes] — restore the reviewed previous version/configuration.
• pin <package_id> <version> / unpin <package_id> — constrain or release the active version.
• disable <package_id> — stop admission into new sessions while retaining recovery evidence.
• remove <package_id> [--yes] — uninstall all marketplace-managed versions.
• report <package_id> --reason TEXT --details TEXT — queue a bounded local registry report.
• keygen, package, and sign-index — publisher/registry authoring commands described in
  Marketplace publication.

Remote refresh/download requires HOLARYN_MARKETPLACE_ENABLED=true. Verification and
policy-approved offline import remain available when it is false. There is no unsigned-executable
or organization-policy bypass flag.

holaryn hacp

Inspect HACP connected-mode configuration (the optional Holaryn Space link).

holaryn hacp status

Prints whether connected mode is configured, and if so the endpoint, scope, node id, and whether an auth token is set. A standalone install reports connected mode: not configured (standalone).

holaryn batch

Import versioned datasets and supervise durable per-row agent execution. Override
the durable host state with --state-dir.

holaryn batch datasets
holaryn batch import <manifest.json> [--sample-size N]
holaryn batch dry-run <definition.json> [--sample-size N]
holaryn batch create <definition.json>
holaryn batch list
holaryn batch show <batch-id>
holaryn batch items <batch-id> [--state STATE] [--limit N] [--offset N]
holaryn batch attempts <batch-id> [--item-key ITEM-KEY]
holaryn batch report <batch-id>
holaryn batch start|pause|resume|cancel|retry <batch-id> --expected-revision N
holaryn batch export <batch-id> <target> --format {csv,jsonl,parquet-ready}
holaryn batch delete <batch-id> --confirmation <batch-id>

pause and cancel require --reason. Repeat --item-key on retry for a
filtered rerun. Definitions are strict JSON and must include configured item/global
budgets plus forecast usage. See Batch and dataset execution.

holaryn self-improve

Manage the evidence-gated candidate-change ledger. State and workspace can be
overridden with --state-dir and --workspace.

holaryn self-improve list
holaryn self-improve show <proposal-id>
holaryn self-improve create <definition.json>
holaryn self-improve patch <proposal-id> <patch.json> --expected-revision N
holaryn self-improve evaluate <proposal-id> <evaluation.json> --expected-revision N
holaryn self-improve plan <proposal-id> <canary.json> --expected-revision N
holaryn self-improve review <proposal-id> --expected-revision N --reviewer ID
                          --verdict {approved,rejected} --rationale TEXT [--elevated]
holaryn self-improve observe <proposal-id> <observation.json> --expected-revision N
holaryn self-improve start-canary <proposal-id> --expected-revision N
holaryn self-improve promote <proposal-id> --expected-revision N
holaryn self-improve cancel <proposal-id> --expected-revision N --reason TEXT
holaryn self-improve export <proposal-id>
holaryn self-improve delete <proposal-id> <confirmation-option> <proposal-id>
holaryn self-improve enable | disable
holaryn self-improve purge <confirmation-option> "DELETE ALL SELF-IMPROVEMENT DATA"

Inputs use strict JSON schemas; unknown fields fail. Every mutation binds to the
current revision, review must be independent, and promotion only records an
authorization artifact. Run the destructive subcommands with --help for the
literal confirmation-option spelling. See
Evidence-gated self-improvement.

holaryn bench

Run reproducible capability and regression evaluations. See
HolarynBench for interpretation, privacy, and live-provider caveats.

holaryn bench list [--suite NAME_OR_JSON]
holaryn bench validate [--suite NAME_OR_JSON] [--release-shape]
holaryn bench run [--suite NAME_OR_JSON] [--mode {offline,live}] [--model ID]
                [--trials N] [--seed N] [--scenario ID]...
                [--output-dir DIR] [--baseline JSON] [--fail-on-regression]
holaryn bench security [--corpus PATH] [--output-dir DIR] [--fail-on-bypass]
holaryn bench routing [--output-dir DIR] [--baseline JSON] [--fail-on-regression]
holaryn bench resilience [--output-dir DIR] [--baseline JSON] [--fail-on-regression]

• list prints stable scenario ids, capability domains, CI requirement, and title.
• validate parses every typed contract; --release-shape additionally requires
  at least 25 scenarios across five domains.
• run writes canonical JSON plus readable Markdown and standalone semantic HTML.
• security runs the versioned no-network injection and information-flow corpus,
  writing content-free JSON and Markdown metrics.
• routing compares static and adaptive selection on the reviewed offline workload.
• resilience exercises safe retry, failover, circuits, partial-stream stop, and
  post-consequential-tool stop without contacting a provider.
• --mode offline is the deterministic, no-network default. --mode live uses a
  configured registry model and may spend tokens or incur provider charges. Live
  shell scenarios require Docker and run with container networking disabled.
• Repeat --scenario to select tasks and use --trials for pass@k evidence.
• --baseline compares reviewed thresholds; --fail-on-regression requires it
  and returns nonzero on a crossed threshold. Any failed trial is always nonzero.

holaryn bench run --suite smoke --output-dir benchmark-results \
  --baseline benchmarks/baselines/smoke-v1.json --fail-on-regression

holaryn routing

Inspect or dry-run adaptive model selection and provider recovery. These commands do not invoke a
provider.

holaryn routing show [--limit N]
holaryn routing simulate PROMPT [--role ROLE] [--tools] [--vision]
                       [--structured-output] [--local-only]
                       [--context-tokens N] [--output-tokens N]
                       [--current-model ID] [--model ID]
holaryn routing reset --yes
holaryn routing health [--limit N]
holaryn routing reset-circuits --yes

simulate holds the representative prompt in memory and prints a content-free candidate decision.
show and reset operate on adaptive-routing decisions/outcomes. health prints provider
circuits, the active recovery policy, metrics, and bounded content-free attempts.
reset-circuits deletes only circuit and recovery-attempt state and requires confirmation. See
Adaptive model routing and Provider recovery.

holaryn memory

Inspect or rebuild local memory. Accepts --path <file> to point at a specific memory database. See Memory.

• status — show the memory backend and location, the active and recorded embedder (and whether they match), and the vector backend.
• reindex — rebuild all memory vectors with the active embedder.
• install-extra {fastembed,mariadb,otel,postgres,qdrant,voice} — install an optional extra into this environment (works in the desktop app's frozen environment too).

holaryn memory status
holaryn memory install-extra fastembed
holaryn memory reindex

holaryn otel

Manage write-only values used by OTLP authentication-header references. Values are accepted only
through a named environment variable and are never printed:

holaryn otel [--state-dir DIR] secret set otel.NAME --value-env ENV_NAME [--replace]
holaryn otel [--state-dir DIR] secret status otel.NAME
holaryn otel [--state-dir DIR] secret clear otel.NAME --confirm "CLEAR otel.NAME"

See Run observability for exporter
configuration and privacy behavior.

holaryn policy

Inspect autonomy policy profiles. Accepts --policy <file.toml> to select a profile explicitly; otherwise the configured one is used.

holaryn policy show

Shows the active policy profile's rules. See Autonomy and approvals.

holaryn encryption

Manage opt-in encrypted local state, per-domain data keys, and password-recoverable backups.
Stop the host before every mutating operation.

holaryn encryption [--state-dir DIR] status [--json]
holaryn encryption [--state-dir DIR] enable [--provider {os,recovery}]
                 [--tenant ID] [--password-env NAME] [--canary-env NAME ...]
holaryn encryption [--state-dir DIR] migrate [--password-env NAME]
                 [--canary-env NAME ...]
holaryn encryption [--state-dir DIR] rotate [--data-class CLASS ...]
                 [--password-env NAME]
holaryn encryption [--state-dir DIR] rewrap --provider {os,recovery}
                 [--password-env NAME]
holaryn encryption [--state-dir DIR] backup OUTPUT [--password-env NAME]
holaryn encryption verify-backup ARCHIVE [--password-env NAME]
holaryn encryption restore-backup ARCHIVE EMPTY_DESTINATION [--password-env NAME]

Recovery material defaults to HOLARYN_ENCRYPTION_RECOVERY_PASSWORD and is intentionally never
accepted as a command argument. enable creates a verified encrypted rollback backup before
migrating existing covered stores. migrate resumes its durable checkpoint. rotate activates
new DEKs while retaining mixed-version reads; rewrap changes only the OS/recovery wrapping
provider. Restore authenticates into a staging tree and refuses non-empty destinations.

See Encrypted local state for the threat model, complete persistent
store inventory, enablement, recovery drill, and key-loss warnings.

holaryn secret

Manage opaque secret references and exact just-in-time leases. Values are accepted only from a
named environment variable and are never printed.

holaryn secret [--state-dir DIR] [--actor ID] list
holaryn secret create ALIAS --value-env NAME --scope-kind KIND --scope-id ID --policy FILE
holaryn secret show SECRETREF
holaryn secret request SECRETREF --principal ID --run ID --tool ID --destination ID \
  --purpose ID --mode MODE --target TARGET [--seconds N]
holaryn secret approve LEASE_ID
holaryn secret test SECRETREF <exact binding and injection options>
holaryn secret rotate-plan SECRETREF
holaryn secret rotate-stage SECRETREF --value-env NAME
holaryn secret rotate-cutover SECRETREF
holaryn secret rotate-rollback SECRETREF
holaryn secret rotate-retire SECRETREF
holaryn secret revoke (--ref SECRETREF | --lease-id LEASE_ID) --reason TEXT
holaryn secret break-glass SECRETREF <exact binding and injection options> \
  --reviewer ID --reason TEXT --confirm "BREAK-GLASS ALIAS"
holaryn secret audit [--limit N]

See Scoped secret broker for policy JSON, rotation, deletion, and
break-glass examples.

holaryn migrate

Import skills, memory, and persona from another agent installation.

holaryn migrate --from {openclaw,hermes} [--home DIR] [--skill-root DIR] [--scope SCOPE]
              [--dry-run] [--yes] [--overwrite]

holaryn migrate --from openclaw --dry-run

holaryn persona

Manage the persona text injected into every session.

• show — print the active persona.
• path — print the persona file location.
• set [text…] [--file FILE] — replace the persona with inline text or the contents of a markdown file.
• clear — delete the persona file.

holaryn persona set --file ./persona.md

holaryn profile

Manage config profiles — named bundles of model, effort, posture, persona, and config overrides that holaryn run --profile, scheduled jobs, and team members can select.

• list — list profiles and the default.
• show <name> — show one profile.
• create <name> / edit <name> — create or edit a profile:

• remove <name> — delete a profile.
• default [name] [--clear] — set or clear the default profile.

holaryn profile create research --model claude-latest --posture selective --effort high
holaryn profile default research

holaryn plan

Review and batch-execute plans staged by dry-run sessions (holaryn run --dry-run or the /dryrun command).

• list — list reviewable staged plans.
• show <plan_id> — show one plan's actions.
• approve <plan_id> — execute the plan's remaining actions, in order.
• discard <plan_id> — discard a plan without executing it.

holaryn plan list
holaryn plan approve p-3

holaryn task-package

Create, inspect, import, remap, and reproduce portable task packages. Package commands
write machine-readable JSON to stdout and send actionable errors with stable
task-package.* codes to stderr.

• schema — print the version 1 manifest JSON Schema.
• keygen --private-key FILE --public-key FILE [--password-env NAME] — create an
  Ed25519 publisher key pair. Passwords are read from environment variables, never
  command-line values.
• scan PLAN --report FILE [--secret-canary-env NAME ...] — inventory a version 1
  export plan and identify secret, privacy, path, license, and binary findings.
• prepare-review REPORT --output FILE --reviewed-by NAME — create a review draft.
  Every decision starts with CHOOSE: and must be explicitly replaced with one of
  the finding's allowed actions before export.
• export PLAN --report FILE --review FILE --output FILE — create a deterministic
  package after the report and explicit review match. Add --signing-key FILE,
  --key-password-env NAME, or --encrypt-password-env NAME as needed.
• inspect PACKAGE [--password-env NAME] — verify and inspect an untrusted archive
  without persisting it.
• preflight PACKAGE [--inventory FILE] — report every missing or incompatible
  dependency, permission, model, account, path, and secret slot before execution.
• import PACKAGE [--inventory FILE] — persist immutable package content and create
  its local default resolution overlay.
• list / show DIGEST — list imported packages or inspect immutable provenance and
  local overlays.
• fork DIGEST OVERLAY_ID [--from-overlay ID] — fork local resolution only.
• remap DIGEST --expected-revision N [--overlay ID] — update a local overlay with
  repeatable --model SOURCE=TARGET, --path SOURCE=TARGET,
  --account SOURCE=TARGET, and --secret-slot SOURCE=TARGET mappings.
• dry-run DIGEST [--overlay ID] [--inventory FILE] — re-evaluate a stored package
  without executing it.
• rerun-reference DIGEST --confirm "RUN DIGEST" — run the deliberately bounded
  reference hash workflow in the sandbox and emit equivalent-output evidence.
• registry-publish DIGEST --registry-dir DIR /
  registry-import REFERENCE --registry-dir DIR — exchange a package through the
  filesystem registry adapter.

Global task-package options are --state-dir DIR, repeatable
--trusted-key PUBLIC_KEY, and --actor NAME. Place them before the subcommand.
Inventory files may be either an array of installed-dependency records or an object
with a dependencies array.

$env:HOLARYN_PACKAGE_CANARY = "known-test-secret"
holaryn task-package scan .\plan.json --report .\scan.json `
  --secret-canary-env HOLARYN_PACKAGE_CANARY
holaryn task-package prepare-review .\scan.json --output .\review.json `
  --reviewed-by operator
# Edit every CHOOSE:<action> value to the selected allowed action.
holaryn task-package export .\plan.json --report .\scan.json `
  --review .\review.json --output .\task.sxtpkg `
  --secret-canary-env HOLARYN_PACKAGE_CANARY
holaryn task-package inspect .\task.sxtpkg

See Shareable task packages for plan, review, inventory, trust,
encryption, hostile-archive, and reproducibility contracts.

holaryn trajectories

Review successful terminal runs and create managed local fine-tuning JSONL.

• candidates [--limit N] — list eligible locally owned completed runs.
• preview RUN_ID ... — print bounded sanitized samples, findings, source
  digest, and the exact consent phrase. Select --format openai-chat,
  sharegpt, or holaryn-episode.
• export RUN_ID ... --preview-id DIGEST --confirm "EXPORT REDACTED TRAJECTORIES"
  — recompute an unchanged review and atomically write the dataset plus
  provenance sidecar.
• list [--limit N] — list managed exports without reading their content.
• delete EXPORT_ID --confirm "DELETE EXPORT_ID" — digest-check and delete
  both managed files. Changed files require --force-changed and the separate
  phrase FORCE DELETE EXPORT_ID.

Place --state-dir DIR and --owner-id ID before the subcommand. System
messages, typed context, and tool results are omitted by default. Opt in with
--include-system, --include-context, or --include-tool-results. Supply
project-specific private values by repeatable environment-variable name:

export HOLARYN_TRAJECTORY_CANARY
holaryn trajectories preview run_0123456789abcdef \
  --private-value-env HOLARYN_TRAJECTORY_CANARY

Raw private values are deliberately not accepted as command-line options. See
Privacy-reviewed training data for the redaction,
stale-preview, format, provenance, and non-effects contracts.