CLI, TUI and ui-cli

The mirasim command#

The standalone archive gives you the built-in agent, transparent Claude and Codex launches, host control, accounts and diagnostics. The `claude` and `codex` commands preserve each agent's own terminal UI and its own authentication — Mirasim changes exactly one thing about them: where their model traffic goes.

./mirasim doctor                        # check the install and its environment
./mirasim                               # Mirasim's built-in agent
./mirasim -p "inspect this repository"  # built-in agent, one-shot
./mirasim claude                        # Claude Code, explicit
./mirasim codex                         # Codex, explicit
./mirasim agents                        # installed versions and updates
./mirasim ssh ubuntu@dev.example.com    # drive a Linux machine over SSH
./mirasim ui-cli help                   # the whole control surface

`mirasim help` prints the authoritative list. The rest of it, grouped by what you would be doing:

Because an agent's TUI paints over the terminal, a launch banner would be invisible within a second. Mirasim therefore publishes its live state into a slot the agent itself renders — Claude's status line, Codex's terminal title — so a mid-session switch to the quota fallback is visible where you are already looking. Your own status line is chained rather than replaced, and external tools can add a segment of their own.

mirasim statusline set deploy "staging ✓"

ui-cli: the app, scriptable#

`ui-cli` is the scriptable twin of the graphical workbench. Every command speaks the exact frames the desktop, mobile and editor surfaces speak, against the same server a window is connected to — so anything a UI can do is one command here, and its effect shows up live in that window. It prints one JSON object per invocation, which is what makes it usable from scripts and from agents.

The `--port` flag picks which Mirasim you are driving. Without it, the command spins up a private throwaway server for itself.

# read-only facts, safe any time
mirasim ui-cli --port 4970 state
mirasim ui-cli --port 4970 sessions --limit 20
mirasim ui-cli --port 4970 workspaces

# start a real run — identical to typing it in the UI
mirasim ui-cli --port 4970 prompt --agent claude \
  --cwd ~/code/proj --text "summarize this repository"

# drive and observe the actual window
mirasim ui-cli --port 4970 navigate --to settings
mirasim ui-cli --port 4970 ui settings.open --value traffic
mirasim ui-cli --port 4970 dom
mirasim ui-cli --port 4970 click --text "By model"
mirasim ui-cli --port 4970 screenshot --out shot.png

Settings as one declarative tree#

Every persisted setting forms a single JSON tree — the default agent, per-agent model, effort and access mode, relay behavior and thresholds, browser and screen automation toggles, display sleep, agent auto-update, the working directory, registered workspaces, IM credentials. You can read the whole thing, set individual dot-paths, or converge a machine onto a desired tree.

mirasim ui-cli --port 4970 config get

mirasim ui-cli --port 4970 config set \
  defaultAgent=codex relay.enabled=true relay.threshold=0.8

# see exactly what would change, then apply only that
mirasim ui-cli --port 4970 config apply --file desired.json --dry-run
mirasim ui-cli --port 4970 config apply --file desired.json

`config apply` diffs your desired tree against the live values and applies only the fields that differ, each through the same setter the Settings UI uses — hot, and idempotent. The reply lists every field it touched with its before and after. Secrets are deliberately not part of the tree: relay keys, account tokens and provider keys go through their own commands.

When a command does not exist yet#

`raw` posts any protocol frame verbatim and prints the responses, which means the CLI's coverage is never the limit — the protocol is. It is the escape hatch for the rare case where the app can do something the command catalog has not named yet.

mirasim ui-cli --port 4970 raw '{"type":"…"}' --await someReplyType --seconds 5