CLI reference

Local herdr-mcp management and operations.

This page covers herdr-mcp commands only. For Herdr workspace, pane, agent and session commands, use the official Herdr CLI reference.

Daily runtime management#

The normal user path is the native Rust CLI installed from a GitHub Release:

Copyherdr-mcp install
herdr-mcp status
herdr-mcp doctor
herdr-mcp permissions status
herdr-mcp update
herdr-mcp update check
herdr-mcp update apply
herdr-mcp update major-apply
herdr-mcp update major-rollback
herdr-mcp update auto
herdr-mcp update status
herdr-mcp worker update
herdr-mcp profile check --file ./workstation-profile.json
herdr-mcp rollback
herdr-mcp reinstall
herdr-mcp uninstall

From v0.4.3 onward, update is the normal one-step user upgrade and is equivalent to update apply. An installed v0.4.2 binary still treats bare herdr-mcp update as the read-only check and reports herdr-mcp update apply as next_action, so use herdr-mcp update apply once when crossing from v0.4.2. Use update check only for an explicit read-only availability/provenance check.

For interactive update / update apply, the CLI keeps the final machine-readable result on stdout and writes human progress to stderr: release/provenance discovery, artifact attestation, bounded download percentage, candidate verification, installer state, and the final health-gated outcome. The downloaded candidate still performs activation in the detached update worker; the foreground CLI observes the durable update job for a bounded interval instead of making the lifecycle mutation itself. After a same-contract Runtime update has committed, the interactive command also checks the user's configured Cloudflare Worker. If its edgeVersion is behind the verified release, Herdr obtains temporary Cloudflare authorization and updates that exact health-proven Worker in place while preserving its Worker identity, Durable Objects, secrets, public OAuth origin, enrolled devices, Connectors and known optional artifact R2 binding; it never changes DNS. If Cloudflare authorization or Worker reconciliation cannot complete, the Runtime stays updated and the result reports next_action: herdr-mcp worker update. Running herdr-mcp update again when the Runtime is already current performs only this pending Worker reconciliation instead of reinstalling the Runtime. If installation legitimately outlives the bounded foreground interval, the command returns an update_queued result with next_action: herdr-mcp update status; update status reports Worker drift once the new Runtime is active. update auto remains non-interactive and never opens Cloudflare authorization, so it reports herdr-mcp worker update as the next action when Edge is stale. The immutable v0.4.2 binary predates this progress UI, so its one-time update apply can remain quiet while doing network work.

herdr-mcp worker update is the direct existing-fleet Edge reconciliation command. Normal user operation requires an enrolled default-instance PROD Runtime and temporary Cloudflare authorization. Fleet-management preflight may identify the exact frozen epoch-2 rollback contract so an already-enrolled legacy Worker can be updated in place, while Link/install data-plane admission remains current/N-1 and still fails closed until the Worker is upgraded. For an exact DEV/UAT candidate, the command is enabled only when HERDR_MCP_EDGE_BUNDLE_PATH explicitly points at the Edge bundle from that same qualified artifact. The update refuses Edge downgrade or unknown contract hashes and fails closed rather than dropping unknown/custom Worker bindings. It does not create a second Worker, rotate device/Connector credentials, change OAuth/DNS identity, or require the ChatGPT Connector to be deleted and re-added.

update apply intentionally refuses an incompatible durable-state schema. For an ordinary v0.4.8 (schema 5) user, the v1.0 (schema 15) transition is one command: herdr-mcp update. The immutable v0.4.8 updater first admits the schema-5 v0.4.9 migration bridge; that detached bridge attests the final schema-15 Runtime, invokes the final Runtime's update major-apply, and then reconciles the already-proven Worker in place. The bridge is never installed as the production service on the successful path.

update major-apply remains the authoritative operator/recovery primitive behind that user path. It first stops the running source service so the final snapshot includes writes committed during shutdown, then creates a private consistent schema-5 SQLite backup plus a private executable copy of the exact old runtime binary, hashes both rollback artifacts, and reuses the normal transactional service install to migrate and activate. A failed backup attempts to restart the source service and reports any restart failure, and preexisting rollback material is rejected before the stop so a retry cannot overwrite an earlier backup. update major-rollback verifies the rollback record and source binary, stops the active service, then verifies the database backup hash and restores that exact pre-upgrade database, and reinstalls the backed-up old runtime. The private binary copy keeps rollback independent of later runtime-generation garbage collection. Rollback accepts a migration interrupted at any schema between 5 and 15, then removes state created after the v1.0 migration. Both major lifecycle commands refuse execution inside managed herdr_exec sessions.

profile check --file is a read-only portability/drift gate. Profile JSON uses schema_version: 1, requires secrets_policy: "reauthorize", and may declare project {id, remote, path} entries plus agent capability requirements such as can_run_headless, supports_code_edit, supports_shell, or supports_vision. It compares those declarations with the current filesystem/Git origin and the existing Capability Inventory; it never installs tools, copies files, or carries credentials. Unknown/unprobed agent traits remain drift rather than being guessed. Run herdr-mcp scan --probe when the report says the inventory is unavailable.

update auto is the scheduler entrypoint. On the default macOS production instance, service install reconciles the owned dev.herdr-mcp.auto-update LaunchAgent. It runs on load and then daily. Automatic installation is intentionally PROD-runtime + Stable-release only: a compiled DEV runtime, [update] check = false, named instances, or preview all skip before network access. When a strictly newer Stable Release exists, the command reuses the normal provenance-verified detached update transaction; it does not introduce a second downloader or bypass rollback gates. service uninstall first arms an owned durable update fence and removes the scheduler; detached workers re-check that fence before activation, so service removal cannot be undone by a queued silent update. An explicit successful install clears the fence.

On macOS, reinstall is the product repair/replacement path. On Linux, runtime repair uses herdr-mcp install and explicit service removal uses herdr-mcp service uninstall; the full ownership-checked product-uninstall transaction described below is a macOS lifecycle integration. It re-applies the managed Rust service lifecycle while preserving configuration and credentials; runtime generations continue to follow normal service GC and retain the active/rollback-safe set. uninstall performs complete cleanup of strongly owned herdr-mcp runtime/config state. The default instance covers its service, owned auto-update scheduler, Link/watchdogs, Native Messaging host, managed user CLI, and config root; a named instance is intentionally limited to its own service/watchdogs/config and never takes ownership of default scheduler/Link/Native Host/user-CLI state. The default product uninstall intentionally leaves one small update-fence tombstone in the user cache after config deletion so a previously detached updater cannot resurrect the service; only an explicit successful install/reinstall clears it. Both deliberately do not uninstall or mutate the independent herdr executable, Herdr service/socket/config, browser extension account state, Cloudflare resources, macOS Keychain entries, or TCC authorization. service uninstall remains the narrower advanced service primitive.

service ..., link ..., native-host ... and candidate are advanced/internal commands. dev is an advanced source-development surface described below. Do not use a repository checkout, Node.js, npm or service install as the normal runtime installation path.

Fast semantic decisions#

herdr-mcp semantic exposes the Runtime's existing provider-neutral semantic layer as a normal CLI surface. Semantic output is advisory; deterministic task, Git, validation, permission, delivery and cleanup facts keep their existing authority.

Copyherdr-mcp semantic status
herdr-mcp semantic setup
herdr-mcp semantic remove <route-name>
herdr-mcp semantic decide --state "..." --question "..." --yes "..." --no "..."
herdr-mcp semantic choose --state "..." --question "..." --option a="..." --option b="..."
herdr-mcp semantic score --state "..." --question "..." --criterion "..." --criterion "..."

setup with no route options uses TypeSafe.ai (decision, jev-latest) as its recommended reference. A custom route supplies --name, --protocol, --url, and --model together. Provider identity is therefore configuration, not a hard-coded decision branch. API keys are never accepted on argv: an interactive terminal uses hidden input, while automation may provide one line on stdin. For typed-decision protocols, setup verifies the exact candidate route before writing it to the existing mode-0600 config.json; a failed verification leaves the previous configuration unchanged. status --json is machine-readable and never returns the API key.

decide, choose, and score all use the same Runtime SemanticService route pool used by browser Auto, planning, Parent orchestration and Work Memory. --state-json accepts structured JSON instead of plain --state text. With no semantic route, the command reports that the decision is unavailable and Herdr's deterministic path remains unchanged.

Source-development runtime: DEV / PROD#

Current runtimes have one explicit path for dogfooding herdr-mcp source without losing a stable recovery source:

Copyherdr-mcp dev status
herdr-mcp dev sync --dry-run
herdr-mcp dev sync
herdr-mcp dev rollback

• dev status is read-only. It reports current runtime channel, active/dev/prod generations, source repo/branch/commit/dirty provenance, whether runtime/current matches recorded state, whether the pinned PROD snapshot validates, and last_transaction for the latest real dev sync. That durable record includes its transaction ID, phase, target source, expected/final generation, terminal error, and activation evidence when available, so callers can resolve the outcome after a self-restart without replaying the sync.
• dev sync --dry-run shows the intended transaction without building or switching runtime state.
• dev sync requires a clean source checkout by default, builds a DEV identity such as <version>-dev, pins the pre-existing PROD binary and SHA-256 evidence under ~/.config/herdr-mcp/runtime/channels/prod/, and persists its transaction in the existing channel state before the potentially long build. It then reuses the normal transactional service install path. Server, Native Host and dev.herdr-mcp.link-prod must reconcile to the same managed generation before the transaction is recorded as succeeded.
• dev sync --allow-dirty is an explicit provenance override for deliberate local experiments. Do not make it the default.
• dev rollback verifies and reinstalls the pinned PROD binary. Repeated DEV syncs preserve that fixed PROD recovery source rather than treating the previous DEV generation as PROD.

DEV/PROD switching is local runtime lifecycle only. It does not deploy Cloudflare Edge, change DNS/OAuth, or create a third persistent test environment. Runtime DEV/PROD is independent from extension DEV/STANDALONE/STORE identity.

macOS permissions#

Copyherdr-mcp permissions status
herdr-mcp permissions setup
herdr-mcp permissions verify

status is granted, denied, needs_setup, unknown, or timeout. setup opens the Full Disk Access pane when possible and does not claim to grant access; macOS still requires explicit user approval. verify checks a protected path through the stable broker. A fresh interactive herdr-mcp install prepares that broker before the service starts and opens the same Full Disk Access pane when authorization is still needed. If file/git tools return macos_tcc_access_blocked, grant Full Disk Access to herdr-mcp-broker, then verify again.

Capability discovery: scan#

doctor answers “is this installation healthy?”. Its default output is a concise human summary: local health, Edge reachability, skipped remote Connector authentication, and only the items that need attention. Use herdr-mcp doctor --verbose for the full layered engineering evidence and herdr-mcp doctor --json for machine-readable output. On macOS, the JSON standalone_extension object reports the managed STANDALONE extension state; state=drift means Google Chrome is loading the fixed standalone extension ID from a path other than ~/.config/herdr-mcp/extensions/standalone/current, and the object includes expected_path, the actual loaded path/profile, Chromium location, and drift_count. Because the browser extension is optional, this advisory does not turn otherwise healthy core MCP/service readiness into a failure. scan answers “which local agent capabilities are actually evidenced on this workstation?”.

Copyherdr-mcp scan
herdr-mcp scan --json
herdr-mcp scan --probe
herdr-mcp scan --refresh --probe

The scan intentionally does not reimplement Herdr's live-agent detection. It combines three evidence sources owned by the installed Herdr/runtime stack:

• agent.list is authoritative for live agent instances, status, pane/workspace and cwd;
• server.agent_manifests is authoritative for the detection manifests loaded by Herdr;
• the installed herdr agent start --help declaration is used to discover the agent kinds that this Herdr build says it can start.

herdr-mcp takes the bounded union of those kinds, looks for the corresponding executable on PATH, and records herdr_startable, executable_available, and the derived available_for_start. A kind is considered available for a new delegation only when the installed Herdr declares it startable and the executable is present. This avoids copying a stale hard-coded Agent-kind list into herdr-mcp while still recording workstation-local availability.

The default scan records bounded --version evidence only for explicitly allowlisted self-description adapters that have passed side-effect smoke tests. --probe additionally runs bounded, non-interactive --help adapters for capabilities that can be proven from the agent's own CLI. A discovered binary with no trusted adapter remains installed-but-unprobed. --refresh explicitly reloads Herdr's agent manifests and bypasses cached probe evidence.

Probe subprocesses receive no stdin, have a three-second timeout and a bounded output capture, and start from a cleared environment with only non-secret runtime variables restored. API keys, bearer tokens and provider credentials are not inherited. Unsupported or ambiguous traits remain unknown; herdr-mcp does not infer provider, model, vision, reasoning quality or code-edit support from an agent name.

Static evidence is kept in a bounded capability inventory under the herdr-mcp config directory. Live status, cwd, project, pane, workspace and session state always come from Herdr/EventCache and are not replaced by the inventory. herdr_inspect.capability_inventory.available_agents exposes every locally available discovered kind by default; HERDR_MCP_AGENT_ALLOW is an explicit operator restriction when a narrower view is required. Availability does not assign a role or require delegation: the Web planner decides from task structure, live load, verified capabilities and resource state, while unknown quality/cost/latency traits remain unknown.

Dynamic planning advice for the Web planner#

The current workstation Runtime Execution Contract is epoch 5 / 18 tools and does not add a dedicated planning tool. The first-party public Edge contract is epoch 8 / 19 actions because herdr_devices is Edge-local. The progressive herdr_skill bootstrap advertises a read-only local method routed through the existing herdr_call tool:

Copyherdr_call(
  method="herdr_mcp.planning.advise",
  params={
    "project_root":"/path/to/project",
    "requires_code_edit":true,
    "requires_shell":true,
    "independent_units":2,
    "ownership_isolated":true
  }
)

The result separates evidence from the decision: live compatible/rejected workers, scan-proven startable-but-not-running Agent kinds, a direct deterministic option, a parallelism opportunity, and workspace/pane/worktree/utility-pane resource facts. The method never starts an Agent, creates a worktree, or auto-selects a worker. Explicit user targets are preserved; required capabilities fail closed when evidence is missing; optional quality/cost/latency traits remain unknown when unverified.

The Web planner can then choose direct execution, reuse an existing Agent, create one new lane, or parallelize only when work is genuinely independent and mutation ownership is isolated. Existing idle/done Agents, worktrees, and duplicate utility panes are exposed as reuse signals; cleanup remains planner-owned after completion rather than becoming a background cleanup daemon.

Fresh GitHub PR / Auto-merge status#

The runtime also exposes another read-only local method through the existing herdr_call tool without changing the 18-tool workstation contract:

Copyherdr_call(
  method="herdr_mcp.github.status",
  params={
    "project_root":"/path/to/project",
    "pr_number":284,
    "previous_fingerprint":"sha256:..."
  }
)

The method reads GitHub through the workstation's authenticated gh CLI on every call. It therefore provides an explicit source=local_gh_api, fresh=true, and cache_policy=bypass_connector_cache boundary for repository Auto-merge settings and PR/check state instead of relying on a Connector projection immediately after a settings mutation. The project root must be a live Herdr-managed Git root and its origin must be on github.com.

When pr_number is present, the result includes the PR state, merge state, Auto-merge request, required checks, and supplemental statuses such as external deployments. Every response has a deterministic state fingerprint. Pass that value back as previous_fingerprint while monitoring a PR; if nothing relevant changed, the next call returns only compact summary counts plus changed=false rather than replaying the complete status table. For active CI monitoring, add wait_ms: 20000 together with previous_fingerprint: the workstation waits locally and then performs one fresh GitHub probe in the same call. A changed state is returned in full; an unchanged state returns compact changed=false with wait_timeout=true. The 20-second ceiling keeps the operation inside the normal Edge request deadline while replacing a separate planner sleep plus status round trip or gh run watch.

Connector and Automation credentials#

Interactive Connectors are approved/revoked from an enrolled-device/operator control channel. Approval grants ordinary MCP access; it does not make the Connector a fleet principal:

Copyherdr-mcp connector approve <approval-request-id>
herdr-mcp connector list
herdr-mcp connector revoke <connector-id> --confirm

The approval command reads the six-digit code interactively; do not put that code on argv or in shell history. Any enrolled device is an equivalent Worker administration channel; there is no owner/member device hierarchy.

Unattended callers such as GitLab CI use independently revocable Automation Clients:

Copyherdr-mcp automation create --name "gitlab:group/project:prod" --device <device-id-or-unique-name>
herdr-mcp automation list
herdr-mcp automation rotate <svc_client_id> --confirm
herdr-mcp automation revoke <svc_client_id> --confirm

create requires an explicit target device and stores the resolved immutable device_id; it never silently chooses among the fleet. create and rotate display client_secret once. Store it directly in the CI secret manager. list never returns secrets and includes the bound device plus bounded issuance metadata. Automation Clients exchange client_id + client_secret for a short-lived access token with OAuth client_credentials; they have ordinary MCP authority only on the bound device, never fleet-admin authority.

Local static bearer credentials, public OAuth Connectors, and Automation Clients are separate boundaries. HERDR_MCP_TOKEN is only the local TCP runtime bearer and does not belong in ChatGPT or GitLab CI.

See ChatGPT Connector.

Health and logs#

Copycurl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8772/
herdr-mcp status
herdr-mcp logs

A local HTTP 200 or 401 proves that the runtime is listening. A connection error indicates a process/port problem.

http://127.0.0.1:8772/mcp is intentionally authenticated even though it is loopback. First-party local clients may obtain the runtime credential from protected local state so the user does not paste it manually; a raw curl/third-party TCP client must send the bearer explicitly. The official browser extension does not use this TCP credential: Chromium Native Messaging reaches the mode-0600 extension.sock trusted IPC path, which is tokenless and strips browser-supplied Authorization.

Watchdog#

macOS can install the runtime watchdog:

Copyherdr-mcp watchdog install
herdr-mcp watchdog status

The watchdog protects herdr-mcp availability. It does not treat every transient Herdr TaskGroup/ExceptionGroup error as a reason to restart the Herdr daemon.

UI language#

Copyherdr-mcp lang en
herdr-mcp lang zh
herdr-mcp lang ja

The browser extension also supports English, Simplified Chinese and Japanese.

Browser Native Messaging host#

Copyherdr-mcp native-host install
herdr-mcp native-host status

Primary path:

CopyChrome extension
  ↓ Native Messaging
native host
  ↓ local Unix socket
herdr-mcp runtime

The browser does not need to store the Herdr bearer. See Browser extension.

Cloudflare Edge credentials#

Copybin/herdr-cloudflare-token --zone example.com --dry-run
bin/herdr-cloudflare-token --zone example.com
bin/herdr-cloudflare-token --zone example.com --verify-only
bin/herdr-cloudflare-token --zone example.com --rotate

See Cloudflare Edge credentials for least-privilege handling.

Custom Domain operations#

Copybin/herdr-cloudflare-domain preflight
bin/herdr-cloudflare-domain status
bin/herdr-cloudflare-domain attach
bin/herdr-cloudflare-domain watch
bin/herdr-cloudflare-domain detach

Legacy CNAME/Tunnel migration only:

Copybin/herdr-custom-domain-cutover preflight
bin/herdr-custom-domain-cutover run

New installations do not need the cutover path. See Cloudflare Edge deployment.

Runtime A/B#

Copybin/herdr-runtime-generation status

bin/herdr-runtime-generation register \
  --generation <id> \
  --endpoint http://127.0.0.1:8773/mcp \
  --runtime-version <version>

bin/herdr-runtime-generation activate --generation <id>
bin/herdr-runtime-generation rollback
bin/herdr-runtime-generation remove --generation <id>

Generation management is for implementation changes within the same public contract epoch: start candidate → verify health/contract → activate → drain old generation. See Runtime A/B.

Self update#

Copybin/herdr-self-update

The supervised updater reuses generation activation and must not be used to silently cross a public contract epoch.

Workstation link#

bin/herdr-link maintains the workstation's outbound authenticated WSS connection to Edge. It carries workstation identity and routes requests to the current active runtime generation. It is normally service-managed rather than run manually.

Common environment variables#

Quick command map#