CLI Reference

Status: Available.

The local gateway is part of the msh client binary. All state lives in ~/.mezite/local/. Commands communicate with the daemon over its Unix socket; msh local status reports the socket path.


msh local install

Register msh local daemon with the OS supervisor (launchd on macOS, systemd on Linux) and seed a default policy.yaml.

msh local install [flags]

# Flags:
#   --system          Install as a system service (Linux + sudo only)
#   --no-service      Seed state only; skip supervisor registration
#   --no-trust-ca     Skip the macOS CA keychain trust step
#   --wait duration   How long to wait for the daemon socket after install (default 10s)
#   --print-unit      Render the service unit / plist to stdout and exit (read-only)

Idempotent — safe to re-run after an upgrade.


msh local status

Show daemon liveness, version, proxy mode, and the locations of its socket and log files.

msh local status [--json] [--quiet]

# Flags:
#   --json    Emit raw JSON instead of the table view
#   --quiet   Print nothing; signal daemon health via exit code only (0=up, 1=down)

msh local shell-init

Print a shell-rc snippet that exports HTTPS_PROXY and CA-bundle env vars so CLIs route through the local gateway proxy. The snippet is gated on msh local status --quiet.

msh local shell-init [bash|zsh|fish] [--listen-addr <addr>]

# Add to ~/.bashrc or ~/.zshrc:
eval "$(msh local shell-init)"

# Add to ~/.config/fish/config.fish:
msh local shell-init fish | source

msh local policy

Inspect and edit the daemon's active policy.

msh local policy show                     # Print the active policy.yaml
msh local policy edit                     # Open in $EDITOR and persist on save
msh local policy reload                   # Force re-read from disk
msh local policy validate --path <file>   # Validate a candidate file without persisting

msh local approval

Inspect and respond to pending escalations. Escalated requests block the AI agent's connection until responded to or timed out.

msh local approval list [--json]               # List pending approvals
msh local approval allow <id> [--reason text]  # Approve a pending request
msh local approval deny  <id> [--reason text]  # Deny a pending request
msh local approval watch                       # Watch and answer approval prompts

msh local audit

Query the audit log (~/.mezite/local/audit.jsonl).

# Show recent entries (server-side filtered)
msh local audit show [flags]
#   --op string     Filter by op (e.g. mitm, pin_splice, block)
#   --host string   Filter by exact host
#   --last uint     Show at most N rows (default 50)
#   --since string  Only rows newer than this duration (e.g. 5m, 24h)
#   --json          Emit JSON

# Stream rows from disk (no daemon required)
msh local audit tail [flags]
#   --lines N        Print the last N matching rows then exit (0 = follow mode)
#   --filter key=val AND-filter rows by field value (repeat for multiple)
#   --json           Emit NDJSON instead of human-readable rows

msh local observe

Manage the daemon's observe-mode session. In observe mode the daemon classifies requests to hosts matching the policy's inspect routes and records what policy would do in enforce mode — without blocking anything, and without writing to the audit log (records go to observe.jsonl). To observe traffic to every domain, add "*" under the policy'sgeneric.inspect block.

msh local observe start [--duration 30m]   # Start a bounded observe session
msh local observe stop                     # Stop the active session
msh local observe status [--json]          # Show session status
msh local observe show [flags]             # List recent observe records
#   --limit uint    Max records to return (default 100)
#   --offset uint   Pagination offset
#   --host string   Filter by exact host
#   --op string     Filter by would-be-decision (allow|escalate|deny)
#   --json          Render as JSON
msh local observe clear --force            # Truncate the observe log

msh local set-proxy-mode / get-proxy-mode

Change or query the daemon's proxy mode at runtime.

msh local set-proxy-mode <off|passthrough|observe|enforce>
msh local get-proxy-mode

msh local classify

Synthesise a request and print the daemon's classification.

msh local classify http <method> <url>
msh local classify cli  <argv>...

# Examples:
msh local classify http GET https://my-cluster.eks.amazonaws.com/api/v1/pods
msh local classify cli kubectl delete pod my-pod -n production

msh local decide

Run the classifier and policy engine together and print the resulting decision.

msh local decide <method> <host> <path> [--json]

msh local inspect

View or edit the MITM inspect list per protocol without editing policy.yaml directly.

msh local inspect summary [--json]                  # Print per-protocol inspect entries
msh local inspect add    <protocol> <entry>         # Add a host / suffix / CIDR
msh local inspect remove <protocol> <entry>         # Remove an entry

msh local pin / unpin / pinned

Manage the user pinned (never-MITM) list. Pinned hosts are spliced through without TLS interception.

msh local pin   <host> [--note text]   # Add a host to the never-MITM list
msh local unpin <host>                 # Remove a host from the list
msh local pinned                       # List all pinned hosts

msh local detector

Inspect and manage the daemon's auto-detected pin cache. Hosts where the upstream cert fails msh local's verification are auto-pinned temporarily.

msh local detector list    [--json]      # List active detector pins
msh local detector clear                 # Wipe the detector pin cache
msh local detector promote <host>        # Move a detector pin to the permanent user list

msh local events

Stream daemon-emitted events.

msh local events [--follow] [--json]

# Common event tags: proxy_mode_changed, policy_reloaded, mitm, splice,
# block, allow, escalate, approval_requested, approval_replied,
# approval_timed_out, host_pinned, host_unpinned

msh local ca

Inspect the daemon's dev CA.

msh local ca info [--json]   # Show path, fingerprint, validity, and trust state

msh local settings

Read and mutate persisted daemon settings (settings.yaml).

msh local settings get                  # Print current settings
msh local settings set <key=value>      # Mutate one setting
msh local settings reload               # Confirm hot-reload and print current proxy_listen

msh local doctor

Run a read-only diagnostic over the msh local install. Reports state-dir permissions, the supervisor unit, and the daemon process. Use msh local repair to fix anything doctor flags.

msh local doctor [--system] [--json]

msh local repair

Diagnose and fix a damaged msh local install.

msh local repair [--system] [--dry-run]
msh local repair --trust-ca              # macOS: (re-)trust the dev CA in the admin domain
sudo msh local repair --untrust-ca       # macOS: remove dev CA certs and orphaned trust settings

msh local uninstall

Remove the msh service, binary, and state directory. The audit log is preserved by default.

msh local uninstall [--system] [--keep-data] [--yes]

msh local upgrade

Download and apply the latest msh release from GitHub.

msh local upgrade [--check] [--dry-run] [--system]

msh local update

Manage the daemon-owned self-update state machine.

msh local update check    [--force]   # Force an immediate check against GitHub Releases
msh local update status   [--json]    # Show current update state-machine snapshot
msh local update apply                # Apply the staged update and restart the daemon

msh local daemon

Start the msh local daemon in foreground (useful for testing without a supervisor).

msh local daemon [--start]

Under a normal msh local install setup the daemon is managed by launchd or systemd. Use msh local daemon only for development or debugging.