MH CLI

Install the CLI with npm (currently macOS Apple Silicon / arm64 only):

npm install -g @motionharness/cli
mh doctor
mh new ./my-project
mh open ./my-project

Or run without a global installation:

npx @motionharness/cli --help

Node.js 22.13+ and pnpm 10.x must already be installed. The CLI does not install or manage them. Project initialization needs registry access to the matching @motionharness/sdk and project dependencies. Run mh skill for the authoring and Agent guide.

@motionharness/cli provides the mh command and selects an exactly matching platform package. @motionharness/cli-darwin-arm64 contains the macOS arm64 native binary; install the main package for the command. Other platforms are not yet supported. Keep optional dependencies enabled. Installation works with --ignore-scripts: there are no postinstall hooks or extra binary downloads.

The npm command uses a short Node package resolver and then execs the Rust CLI. mh open [directory] returns a Studio URL and exits without opening a browser. Use --browser to open it explicitly. Project commands default to the current working directory (--project selects another) and start sessions on demand. mh status and mh close inspect or release the current project; mh daemon status lists all projects and mh daemon stop explicitly stops everything. A session closes after 15 minutes without connected Studios or running work. An empty daemon exits after 10 minutes. Busy projects and failed saves prevent normal close/reclamation. Node runs only for transient build/dependency tasks; Chrome automation uses Rust chromiumoxide.

The binary embeds MH's fixed runtime resources. On first use these expand into ~/Library/Caches/mh/runtime/<payload-sha256>/. MH_CACHE_DIR can select an absolute private writable base; mh doctor reports the resource location. A damaged cache is an error: stop processes using the affected hash, remove only that hash directory and retry. Older hashes are retained across upgrades.

Upgrade with mh update (or npm install -g @motionharness/cli@latest); uninstall with npm uninstall -g @motionharness/cli. Cached runtime resources remain on disk. The independently distributed native binary continues to work without npm.

The public CLI collects anonymous usage events by default: command and run outcomes, Studio control clicks and keys outside text editors, versions, system details, and the coding agent when identifiable. An installation uses a random local ID. Source code, projects, assets, paths, command arguments, and typed text are not uploaded. A bounded local queue retries failed uploads without changing command output or exit status.

Updates

mh update --check             # Query latest without installing
mh update                    # Upgrade a confirmed npm global installation
mh update --check --output-format json      # Structured result for scripts
mh update --timeout-seconds 300

The npm launcher queries the configured npm registry in global mode (including user/global npm configuration and environment settings, excluding project .npmrc). It compares semantic versions against latest, never downgrades, and installs the exact checked version with its matching platform package. Automatic installation requires the current package to be directly inside the active npm global root with a matching prefix; linked packages and detected pnpm/yarn layouts are excluded. If a different Node/npm installation is active, switch back to the one that owns MH. Project-local, npx and other package-manager installs receive manual instructions. Standalone binaries must be replaced manually.

Updates retain the npm prefix, enable optional dependencies and disable install scripts. Success means the entry package, platform package and native executable all report the requested version. No administrator escalation is attempted. npm installation is not an atomic transaction: errors, interruption or timeout can leave an incomplete installation; follow the reported reinstall instruction. Concurrent updates to the same installation wait for a lock within the timeout. A stale lock error names the file to remove after confirming no update is running. Old runtime caches are retained.

Ordinary interactive commands check in parallel at most once every 12 hours, with a three-second limit. Checks stop when the command exits. Notices go to stderr and show the current/latest versions. Network or cache failures are silent and do not change the command's result. Checks are disabled for non-interactive runs, CI, default JSON output, help and version output. Set MH_NO_UPDATE_NOTIFIER=1 to opt out. Attempts and results are cached separately under mh/updates in the user's cache directory (on macOS, ~/Library/Caches, or absolute XDG_CACHE_HOME).

Explicit update --check bypasses that cache and reports registry errors. Its successful exit status is 0 even when an update is available. Default JSON output returns ok, currentVersion, latestVersion, updateAvailable and updated; successful installation additionally includes installedVersion. Errors and unsupported installation attempts exit nonzero; npm logs never mix into JSON stdout.