CLI Command Reference#

The MUTX CLI distribution lives at repo root and installs the mutx entrypoint from pyproject.toml.

Install#

Fastest macOS path:

brew tap mutx-dev/homebrew-tap
brew install mutx
mutx setup hosted

This path installs MUTX through Homebrew, then hands onboarding off to the CLI itself.

🦞 The setup handoff now enters a MUTX-owned wizard. Hosted is the recommended lane, OpenClaw is the default personal assistant runtime, and MUTX tracks the real upstream OpenClaw home rather than relocating it.

Editable local install with the operator TUI:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e ".[dev,tui]"

Homebrew install from the third-party tap:

brew tap mutx-dev/homebrew-tap
brew install mutx

The published tap is updated from cli-vX.Y.Z release tags. Pushing main by itself does not move Homebrew.

The tap formula is expected to smoke-test the package with non-networked command help such as mutx --help, mutx setup --help, and mutx doctor --help.

If Homebrew says mutx is installed but not linked, there is usually an older mutx shim already present in /opt/homebrew/bin. Relink the Homebrew binary with:

brew link --overwrite mutx
hash -r
which mutx

If you want to inspect the conflict before overwriting:

brew link --overwrite mutx --dry-run

If mutx still fails with ModuleNotFoundError: No module named 'cli', your shell is still resolving the stale wrapper rather than the Homebrew-managed executable.

Configuration#

The CLI stores configuration in ~/.mutx/config.json and reuses the existing CLIConfig shape from cli/config.py:

{
  "api_url": "http://localhost:8000",
  "access_token": null,
  "refresh_token": null,
  "assistant_defaults": {
    "provider": "openclaw",
    "template": "personal_assistant",
    "runtime": "openclaw",
    "model": "openai/gpt-5"
  }
}

Config precedence is:

1. CLI flag
2. MUTX_API_URL
3. config file
4. default

You can override the API URL per command:

mutx --api-url http://localhost:8000 doctor

Or with an environment variable:

export MUTX_API_URL=http://localhost:8000

Canonical Setup Flow#

Recommended direct setup:

mutx setup hosted --install-openclaw --open-tui

Advanced local operator:

mutx setup local --install-openclaw --open-tui

If OpenClaw already exists on the machine and you just want MUTX to adopt it for tracking:

mutx setup hosted --import-openclaw
mutx setup local --import-openclaw

Hosted setup authenticates against the configured control plane. Local setup can provision a managed localhost stack under ~/.mutx/runtime/local-control, start http://localhost:8000, bootstrap a trusted local operator session, deploy Personal Assistant, and open the TUI without asking for email or password.

Both lanes now:

• keep MUTX in charge of the flow
• detect an existing OpenClaw install and import its binary/home paths into MUTX tracking
• install OpenClaw on demand
• resume upstream openclaw onboard --install-daemon when needed
• track the runtime in ~/.mutx/providers/openclaw
• sync a last-seen provider snapshot back to the control plane for the web dashboard
• keep local OpenClaw gateway keys on the operator machine instead of uploading them

Core Commands#

Setup + health#

Auth#

Assistants#

Agents + deployments#

Compatibility commands#

The older flat commands remain available for compatibility:

• mutx login
• mutx logout
• mutx whoami
• mutx status
• legacy agents and deploy groups

Operator TUI#

Launch the first-party Textual shell with:

mutx tui

The TUI now centers the assistant-first operator path:

• Setup: auth state, provider cards, wizard steps, runtime pointers, and starter deployment entrypoint Existing OpenClaw installs expose Import Existing OpenClaw 🦞, a repair path, and Open OpenClaw TUI 🦞.
• Assistant: assistant overview, status, and deployment context
• Deployments: deployment inventory and controls
• Control Plane: sessions and gateway detail

Key bindings:

• r refresh the active pane
• d deploy the default assistant from setup
• x restart the selected deployment
• s scale the selected deployment
• backspace delete the selected deployment
• q quit

If no local auth is stored, the TUI still launches and shows the local CLI state instead of crashing.

Smoke Validation#

Local editable install and command smoke:

pip install -e ".[dev,tui]"
mutx doctor --output json
mutx --help

Local stack validation:

make dev-up
mutx setup local --name "Local Operator" --install-openclaw --no-input
mutx doctor
mutx assistant overview
mutx runtime inspect openclaw
mutx runtime open openclaw --surface tui
mutx tui

Targeted contract coverage:

pytest tests/test_cli_auth_and_tui.py tests/test_cli_setup_and_doctor.py

Release Truth#

• The CLI distribution version is the root pyproject.toml version.
• The recommended CLI git tag format is cli-vX.Y.Z.
• The Homebrew tap formula should point at the matching cli-vX.Y.Z source archive and use mutx --help as its non-network test.
• The SDK has its own package metadata under sdk/pyproject.toml; do not treat SDK and CLI release tags as the same thing.