@meego-harness/worker-cli

Unified worker discovery, provisioning, runtime control, and diagnostics CLI for meego-harness.

Install:

pnpm add @meego-harness/worker-cli

If you are testing from a local workspace checkout before publish, use pnpm exec meego-harness-worker ....

If the package is available from your registry, you can start the UI without a prior local install:

npx @meego-harness/worker-cli gui
npx @meego-harness/worker-cli gui --host 127.0.0.1 --port 0

Top-level commands:

meego-harness-worker onboard
meego-harness-worker gui
meego-harness-worker upgrade
meego-harness-worker import-existing --json
meego-harness-worker onboard --all --json
meego-harness-worker start --worker codex-worker-1 --tmux
meego-harness-worker start --all --tmux
meego-harness-worker start --resume
meego-harness-worker stop --worker codex-worker-1
meego-harness-worker stop --all
meego-harness-worker stop --tmux-only
meego-harness-worker doctor
meego-harness-worker doctor --fix

onboard

onboard is the only provisioning and management entrypoint. It does not start workers.

Interactive onboard can:

• search npmjs and configured registries
• install missing worker packages
• create new worker instances
• delete configured worker instances
• add or remove registries
• set machine-level defaults for serverUrl and email
• save, apply, and remove machine-local profiles

Examples:

meego-harness-worker onboard
meego-harness-worker onboard codex
meego-harness-worker onboard --all
meego-harness-worker onboard --json

onboard --all installs every discovered worker package but does not run setup or start. onboard --json prints the current worker-cli state snapshot, including packages, instances, registries, defaults, profiles, and a summary of changes.

gui

gui starts a local web UI for worker configuration, prints the URL, and opens it in your browser. It listens on port 4567 by default and moves to the next port when that port is already in use. Pass --port 0 to request a system-assigned port, or --no-open to keep the browser closed.

meego-harness-worker gui
meego-harness-worker gui --host 127.0.0.1 --port 0
meego-harness-worker gui --no-open

The web UI can:

• set worker defaults
• configure worker gateway URLs
• add or remove custom registries
• save or remove package profiles
• install worker packages
• update or uninstall worker packages
• create or delete configured worker instances
• import compatible workers installed through older standalone packages

Worker creation still runs the selected worker package setup action. The GUI passes common setup fields as CLI arguments; package-specific missing fields are reported by that setup action.

upgrade

upgrade stops configured workers, upgrades every worker package currently managed by worker-cli, and resumes the workers that were stopped. It does not discover or install new packages.

meego-harness-worker upgrade
meego-harness-worker upgrade --json
npx @meego-harness/worker-cli@latest upgrade

start

start only controls runtime startup.

meego-harness-worker start --worker codex-worker-1 --tmux
meego-harness-worker start --all --tmux
meego-harness-worker start --resume

Notes:

• --tmux is only supported for workers whose manifest declares runtimeKind = foreground-process.
• start --resume restarts instances previously marked by stop --all.

stop

stop only controls runtime shutdown.

meego-harness-worker stop --worker codex-worker-1
meego-harness-worker stop --all
meego-harness-worker stop --tmux-only

Notes:

• stop --all records the last known start mode for later start --resume.
• stop --tmux-only only kills worker-cli managed tmux sessions.

doctor

doctor performs health diagnostics across environment, registries, packages, and worker instances.

meego-harness-worker doctor
meego-harness-worker doctor --worker codex-worker-1
meego-harness-worker doctor --fix

doctor --fix only applies explicit fixable actions such as:

• installing tmux
• reinstalling a missing worker package
• removing dangling worker instance records

It does not auto-fix high-risk host-service or worker-specific business configuration issues.