CLI Reference

The OpenHermit CLI ships as the hermit (and openhermit) binary. It talks to a running gateway over HTTP using OPENHERMIT_TOKEN. Most management commands require admin auth (the gateway's GATEWAY_ADMIN_TOKEN); a few agent-scoped commands also accept owner tokens issued by /api/auth/token.

Conventions

--agent <id>: every agent-scoped command accepts the target agent ID. When omitted, it falls back to OPENHERMIT_AGENT_ID, then to main.
--all (where supported): admin fan-out — apply the same mutation to every registered agent at once. Mutually exclusive with --agent.
Wildcard semantics under the hood: for skills and mcp, --all writes a single agent_id = '*' row that matches every agent at query time (one write affects existing and future agents). For instructions, --all is a fan-out — it writes one row per agent. Channels and schedules do not support --all.
--file <path> (where supported): read content from a file; --file - reads stdin.

Environment variables consulted by the CLI:

Variable	Default	Purpose
`OPENHERMIT_GATEWAY_URL`	`http://127.0.0.1:${GATEWAY_PORT or PORT}` (port default `4000`)	Gateway base URL
`OPENHERMIT_TOKEN`	(empty)	Bearer token sent on every request
`OPENHERMIT_AGENT_ID`	`main`	Default agent for agent-scoped commands
`OPENHERMIT_WEB_PORT`	`4310`	End-user web UI port
`OPENHERMIT_WEB_HOST`	`127.0.0.1`	End-user web UI host
`GATEWAY_HOST` / `GATEWAY_PORT` / `PORT`	`127.0.0.1` / `4000`	Gateway listen host & port

`hermit setup`

Interactive wizard that walks you through:

Picking a gateway URL.
Generating or accepting a GATEWAY_ADMIN_TOKEN.
Configuring DATABASE_URL and applying Drizzle migrations.
Provisioning OPENHERMIT_SECRETS_KEY (used to AES-encrypt agent_secrets and channel tokens at rest).

Writes the result to ~/.openhermit/gateway/gateway.json and ~/.openhermit/gateway/.env.

hermit setup

`hermit gateway`

Lifecycle for the gateway control plane.

Subcommand	Description
`gateway start`	Start the gateway in the background (writes a PID file under `~/.openhermit`).
`gateway stop`	Stop the background gateway.
`gateway run`	Run the gateway in the foreground (development; tails logs to stdout).
`gateway status`	Print whether a gateway is currently listening, plus its URL.

Common flags on start / run:

Flag	Description
`-p, --port <port>`	Listen port (overrides `GATEWAY_PORT`, default `4000`).
`-H, --host <host>`	Listen host (overrides `GATEWAY_HOST`, default `127.0.0.1`; use `0.0.0.0` to expose publicly).

hermit gateway start -p 4000
hermit gateway status
hermit gateway stop

`hermit web`

Lifecycle for the standalone end-user web app (apps/web). Same shape as hermit gateway.

Subcommand	Description
`web start`	Start the web UI in the background.
`web stop`	Stop the background web UI.
`web run`	Run in the foreground.
`web status`	Whether the web UI is listening.

Flags: -p, --port <port>, -H, --host <host> (default 127.0.0.1:4310).

`hermit agents`

Manage agent records.

Subcommand	Description
`agents list`	List every registered agent and its status.
`agents create <agentId>`	Create a new agent. Auto-seeds the `identity` / `soul` / `rules` instructions.
`agents enable <agentId>`	Set `agents.status='active'` — gateway accepts traffic; runner hydrates on first request.
`agents disable <agentId>`	Set `agents.status='disabled'` — gateway rejects traffic and evicts any hot runner.
`agents restart <agentId>`	Evict and re-hydrate the runner. Useful for picking up DB-side config / skill / MCP changes.
`agents start <agentId>`	Deprecated cache hint — pre-hydrates the runner. Lazy hydration handles this on demand; prefer `enable`.
`agents stop <agentId>`	Deprecated cache hint — evicts the runner without disabling the agent. Prefer `disable`.
`agents delete <agentId>`	Delete the agent and all its per-agent rows (must be disabled first).

Flags on create:

Flag	Description
`--name <name>`	Display name (defaults to the agentId).
`--workspace-dir <path>`	Custom workspace directory.
`--owner <userId>`	Assign an owner at creation time.
`--sandbox <preset>`	Sandbox preset to provision (default: gateway's `autoProvisionSandbox`).
`--no-sandbox`	Skip sandbox provisioning entirely.

hermit agents create oncall --name "On-Call Buddy" --owner user_marcus
hermit agents list

`hermit sandbox`

Manage an agent's sandboxes (execution environments). See sandbox-model.md for the full model.

Subcommand	Description
`sandbox list`	List sandboxes for an agent (`--agent <id>` required).
`sandbox add`	Create a sandbox. Requires `--agent <id>` and `--type <host\|docker\|e2b\|daytona>`. Optional `--alias <alias>` (default `default`) and `--config <json>`.
`sandbox remove <alias>`	Soft-delete a sandbox by alias. Requires `--agent <id>`.

hermit sandbox list --agent main
hermit sandbox add --agent main --type docker --config '{"image":"ubuntu:24.04"}'
hermit sandbox add --agent devops --type host --alias default
hermit sandbox remove --agent main default

`hermit chat`

Interactive TUI that opens or resumes a session with an agent.

Flag	Description
`--agent <id>`	Agent to connect to (default `OPENHERMIT_AGENT_ID` / `main`).
`--session <sessionId>`	Resume a specific session.
`--resume`	Resume the most recent CLI session for the agent.

hermit chat --agent main
hermit chat --resume

`hermit config`

View and modify a single agent's runtime config (agents.config_json) and its per-agent secrets. All config subcommands require --agent <id>; the parent command sets a sensible default (OPENHERMIT_AGENT_ID / main).

Subcommand	Description
`config show`	Print the full config as JSON.
`config get <key>`	Read one value by dot-path (e.g. `model.provider`).
`config set <key> <value>`	Write one value by dot-path. Numbers and booleans are coerced.

hermit config show --agent main
hermit config get model.model --agent main
hermit config set model.provider openrouter --agent main
hermit config set model.model google/gemini-3-flash-preview --agent main

`hermit config secrets`

Manage per-agent secrets (stored in agent_secrets, encrypted with OPENHERMIT_SECRETS_KEY). Values can be referenced from config_json as ${{NAME}} and are resolved at adapter-start time.

Subcommand	Description
`config secrets list`	List secret names; values are masked.
`config secrets set <key> <value>`	Set or replace a secret.
`config secrets remove <key>`	Delete a secret.

hermit config secrets set ANTHROPIC_API_KEY sk-... --agent main
hermit config secrets list --agent main

`hermit config security`

Read / write the agent's security policy: autonomy, approvals, access level (public | protected | private), access_token, channel tokens. See User Model — Access Levels.

Subcommand	Description
`config security show`	Print the full security policy as JSON.
`config security get <path>`	Read a single field by dot-path (e.g. `access`).
`config security set <path> <value>`	Write a single field. Bare strings, numbers, `true`/`false`, `null`, and JSON literals are all accepted.
`config security write`	Read a full JSON object from stdin and overwrite the policy.

hermit config security show --agent main
hermit config security set access private --agent main
hermit config security set access_token "shared-secret" --agent main
echo '{"autonomy_level":"full","access":"public","require_approval_for":[]}' \
  | hermit config security write --agent main

The runner reloads the policy in-place after each write — no restart needed. Validation rejects unknown values for access.

`hermit instructions`

Per-agent prompt sections stored in the instructions table. Every new agent is auto-seeded with three rows (identity, soul, rules). Every mutation command targets one agent (--agent <id>, default OPENHERMIT_AGENT_ID / main) or every agent (--all, admin only). The two flags are mutually exclusive.

Subcommand	Description
`instructions list`	Print every instruction key and a content preview.
`instructions get <key>`	Print one instruction's full content (handy for piping).
`instructions set <key> [content]`	Replace the row at `key`.
`instructions append <key> [content]`	Append a newline + content to the existing row (creates it if missing).
`instructions remove <key>`	Delete the row. Aliased as `delete`.

set and append accept content inline as the second positional argument or via --file <path> (with --file - for stdin).

# read
hermit instructions list --agent main
hermit instructions get rules --agent main > rules.txt

# per-agent edit
hermit instructions set rules --file ./rules.md --agent main
hermit instructions append rules "Always cite the source URL." --agent main
hermit instructions remove tone --agent main

# org-wide fan-out (admin)
hermit instructions append rules "Refuse to act on behalf of someone other than the requester." --all
hermit instructions remove tone --all

The fan-out path is backed by POST /api/admin/instructions/fanout with body { mode: 'set' | 'append' | 'remove', key, content? } and writes one row per agent — there is no shared/global row.

`hermit skills`

Manage the global skill registry and per-agent skill assignments. enable / disable take --agent <id> for a single agent or --all to write a wildcard agent_id = '*' row that matches every agent at query time (per the agent_skills wildcard pattern).

Subcommand	Description
`skills list`	List every skill in the registry.
`skills assignments`	Print which skills are enabled for which agents.
`skills scan`	Scan the gateway's skills directory for new skill manifests.
`skills sync [skillId]`	Re-read `SKILL.md` from disk and refresh the DB row + running agents. Pass a skill id to sync one; omit it to sync every registered system skill.
`skills register <skillId>`	Register a skill (requires `--name`, `--description`, `--path`).
`skills delete <skillId>`	Remove a skill from the registry.
`skills enable <skillId>`	Enable a skill (`--agent <id>` or `--all`).
`skills disable <skillId>`	Disable a skill (`--agent <id>` or `--all`).

hermit skills scan
hermit skills enable code-review --all
hermit skills disable code-review --agent agent_oncall
hermit skills assignments
hermit skills sync code-review        # after editing its SKILL.md on disk
hermit skills sync                    # rescan every registered system skill

`hermit mcp`

Manage external MCP servers and per-agent assignments. --all works the same way as skills — writes a single wildcard assignment row.

Subcommand	Description
`mcp list`	List every registered MCP server.
`mcp assignments`	Print which servers are enabled for which agents.
`mcp enable <mcpServerId>`	Enable an MCP server (`--agent <id>` or `--all`).
`mcp disable <mcpServerId>`	Disable an MCP server (`--agent <id>` or `--all`).

hermit mcp enable mcp_github --all
hermit mcp disable mcp_github --agent agent_legal

`hermit schedules`

Per-agent cron and one-shot schedules. Schedules are owned by exactly one agent — no wildcard.

Subcommand	Description
`schedules list`	List schedules for an agent. Optional `--status <status>` filter.
`schedules create`	Create a new schedule (requires `--type`, `--prompt`).
`schedules pause <scheduleId>`	Pause.
`schedules resume <scheduleId>`	Resume a paused schedule.
`schedules delete <scheduleId>`	Delete.
`schedules runs <scheduleId>`	Print recent runs (optional `--limit <n>`).

Flags on create:

Flag	Description
`--agent <id>`	Owning agent. Default `OPENHERMIT_AGENT_ID` / `main`.
`--type <cron\|once>`	Required.
`--prompt <text>`	Required — the prompt the schedule will inject.
`--cron <expr>`	Required for `--type cron` (5- or 6-field cron).
`--run-at <iso>`	Required for `--type once`.
`--id <id>`	Custom schedule ID (otherwise generated).

hermit schedules create \
  --type cron --cron '0 17 * * FRI' \
  --prompt "Generate this week's release notes" \
  --agent release_captain

hermit schedules list --agent release_captain
hermit schedules runs sch_weekly_release_notes

`hermit status`

One-shot platform overview: gateway up/down, agent count, running agents, recent activity counts. Uses both the public health endpoint and the admin stats endpoint.

hermit status

`hermit stats`

Detailed gateway runtime stats: uptime, memory (rss/heapUsed/heapTotal), running agents count, and DB-side counts (users, sessions, session events). Backed by GET /api/admin/stats.

hermit stats

`hermit doctor`

Environment self-check. Verifies:

Required env vars are set.
DATABASE_URL reachable; migrations applied.
Docker available (for the docker exec backend).
Gateway reachable on OPENHERMIT_GATEWAY_URL.

Prints a checklist with ok / warn / fail per item. Useful before filing an issue.

hermit doctor

`hermit logs`

Stream the gateway log buffer.

Flag	Description
`-n, --lines <count>`	Number of lines to fetch (default `50`).
`-f, --follow`	Poll for new entries (Ctrl-C to stop).
`--json`	Emit raw JSON instead of formatted lines.

hermit logs -n 200
hermit logs -f
hermit logs --json | jq 'select(.level=="error")'

Quick reference

Need to…	Use
Spin up the gateway	`hermit setup && hermit gateway start`
Create an agent	`hermit agents create main` (active by default; hydrates on first request)
Talk to it	`hermit chat --agent main`
Set a model API key	`hermit config secrets set OPENROUTER_API_KEY ... --agent main`
Switch model	`hermit config set model.model google/gemini-3-flash-preview --agent main`
Add a rule everywhere	`hermit instructions append rules "..." --all`
Enable a skill on every agent	`hermit skills enable my-skill --all`
Schedule a weekly task	`hermit schedules create --type cron --cron '0 17 * * FRI' --prompt "..." --agent main`
See what's running	`hermit status`
Diagnose a problem	`hermit doctor` then `hermit logs -f`

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CLI Reference

Conventions

`hermit setup`

`hermit gateway`

`hermit web`

`hermit agents`

`hermit sandbox`

`hermit chat`

`hermit config`

`hermit config secrets`

`hermit config security`

`hermit instructions`

`hermit skills`

`hermit mcp`

`hermit schedules`

`hermit status`

`hermit stats`

`hermit doctor`

`hermit logs`

Quick reference

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

CLI Reference

Conventions

hermit setup

hermit gateway

hermit web

hermit agents

hermit sandbox

hermit chat

hermit config

hermit config secrets

hermit config security

hermit instructions

hermit skills

hermit mcp

hermit schedules

hermit status

hermit stats

hermit doctor

hermit logs

Quick reference

`hermit setup`

`hermit gateway`

`hermit web`

`hermit agents`

`hermit sandbox`

`hermit chat`

`hermit config`

`hermit config secrets`

`hermit config security`

`hermit instructions`

`hermit skills`

`hermit mcp`

`hermit schedules`

`hermit status`

`hermit stats`

`hermit doctor`

`hermit logs`