> ## Documentation Index > Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt > Use this file to discover all available pages before exploring further. # Monolex CLI > Control a running Monolex desktop app: tabs, PTY input and extraction, remote sessions, projects, files, authentication, and OpenCLIs tools. `monolex-cli` is the automation surface for a **running Monolex Tauri desktop app**. It talks to the app's local control boundary; it is not a substitute for starting the desktop app, the headless server, or the PTY daemon. *Public OpenCLIs metadata: `monolex-cli 0.2.1`, registry build `2026-04-10-065301`. The CDN artifact URL currently names build `2026-04-08-205635`, and the published payload self-identifies as `monolex-cli 0.2.0`. The command inventory below was verified against that exact payload; these three release identities are not claimed to agree. The installed macOS binary is byte-identical to the CDN payload despite its different OpenCLIs build directory.* *Registry ownership: the public `monolex-cli` row points its canonical `docs_url` to this page, its product homepage to `https://monolex.ai`, and its relationships to Monopty, Monosystem, Monolex Headless, and OpenCLIs. Repository ownership remains `monolex/monolex`; no public source URL is advertised while that repository is private.* ## Quick Start ```bash theme={null} openclis install monolex-cli monolex-cli --version monolex-cli status --json monolex-cli tab-list --json monolex-cli command-list --json ``` Start the Monolex desktop app before running control commands. `--json` is a global machine-readable output switch and is also shown by every subcommand. The parser exposes 19 operational commands plus Clap's generated `help`. ## Release and Transport Identity | Proof surface | Current value | What it proves | | --------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | OpenCLIs installed state | Version `0.2.1`, build `2026-04-10-065301` | Registry/install-directory identity | | CDN `latest.json` | Version `0.2.1`, build `2026-04-10-065301`, path `0.2.1/2026-04-08-205635` | The public pointer intentionally contains a path/build mismatch | | CDN `meta.json` | Version `0.2.1`, build `2026-04-08-205635` | Artifact-manifest identity | | Executing payload | `monolex-cli 0.2.0` | The version compiled into the binary | | Installed/CDN macOS payload | SHA-256 `4b5e190ecde6b6dc7abe81e275977ce3a7f1dc56f507e376417d9e03385b04dc` for the extracted executable | Installed and public macOS executables are byte-identical | The release contains `darwin-aarch64`, `linux-x86_64`, `linux-aarch64`, and `windows-x86_64` artifacts. There is no published Intel macOS or Windows ARM64 artifact in this release. On Unix, the CLI discovers a live `~/.monolex/runtime/sockets/app/control-app-.sock`; dead-PID socket files are removed during discovery. On Windows, it reads a `control-app-.pid` marker and connects to the `monolex-control-app-` named pipe. Version 0.2.0 has no `--socket` override and selects the first live discovered app endpoint. ## Output Contract With `--json`, a successful app reply stays wrapped as `{"ok":true,"data":...}`. Without it, most commands print only `data`; `get-answer` prints only extracted `content`. Connection, parse, and other transport failures exit non-zero. In JSON mode those transport failures are written to stderr as `{"ok":false,"error":...}`, so consumers must check both the exit status and output channel. The published 0.2.0 payload has no initiate guide path: `monolex-cli` without a command prints Clap help to stderr and exits `2`. Current source now owns an authored `src/initiate/initiate.md` and `src/initiate/SKILL.md` for the next packaged guide surface, but that source-ahead documentation does not retroactively change the public payload. Use `monolex-cli --help` for a successful read-only discovery call today. ## Complete Command Reference ### App, tabs, and terminal I/O | Command | What it does | Arguments and controls | | -------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `status` | Reports whether the app control surface is reachable and its current state. | Read-only; add `--json`. | | `tab-list` | Lists PTY sessions visible to the desktop control boundary, including child PID and idle time. | Read-only; use the returned `id` as the PTY session id. | | `tab-new` | Emits the same `control-tab-new` event used by the desktop UI path. | Accepts `--cols` 120, `--rows` 40, `--command`, `--cwd`, and `--provider` (`claude`, `gemini`, `codex`, `cursor`, `copilot`, `kiro`, `opencode`). The current app ignores cols/rows and owns final sizing. Success acknowledges event emission, not the eventual PTY id. | | `tab-switch ` | Requests a full grid update for one PTY session. | Returns `frameDispatched` and `channelHash`; it does not itself prove visible frontend focus changed. | | `write ` | Writes raw terminal data. | Decodes `\r`, `\n`, `\t`, and `\x03`; can execute or interrupt terminal programs. | | `wait-idle ` | Waits until output has been quiet for a defined interval. | `--idle-ms` default 500; `--max-wait` default 30 seconds. | | `get-answer ` | Finds the last exact prompt match and returns from that row to the bottom. | Extraction is screen/text based; use the exact prompt for a precise boundary. | | `command-list` | Lists app-side control-protocol commands grouped with enabled/disabled state. | Always callable, but it is not the installed CLI parser inventory; see the protocol distinction below. | ### Projects, files, and gateway state | Command | What it does | Arguments and controls | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `project-list` | Lists known projects with folder paths. | Read-only. | | `open-file ` | Opens Markdown, MDX, code, or another supported file in the Monolex viewer. | Changes the desktop viewer; it does not edit the file. | | `gateway-info` | Shows the desktop gateway `session_id` and policy token. | Treat policy tokens as credentials; avoid logs and public output. | | `auth-login --api-key ` | Sends a raw API key to the app, which exchanges it using the app's device id and installs the resulting gateway token. | Accepts `MONOLEX_API_KEY`; mutates shared authentication state. Never place the key on shared command lines or logs. | ### Remote desktop sessions | Command | What it does | Arguments and controls | | ------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------- | | `remote-connect ` | Connects the app to one remote terminal session. | Optional `--label`; the policy token grants session access. | | `remote-auto-connect` | Discovers and connects to all eligible other machines. | Potentially opens multiple live remote connections. | | `remote-list` | Lists active remote connections. | Read-only. | | `remote-disconnect ` | Disconnects one remote session from the app. | Connection-state mutation; does not delete the remote machine. | ### OpenCLIs tools | Command | What it does | Arguments and controls | | --------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------- | | `tool-install [tool]` | Installs one OpenCLIs package through the desktop bridge. | Omitting the tool installs OpenCLIs itself. | | `tool-list` | Lists OpenCLIs tools visible to the app. | Read-only registry/install view. | | `tool-update` | Updates all installed OpenCLIs tools. | Network and executable mutation; verify resulting versions separately. | ## CLI Parser vs App Control Protocol The shipped CLI and the current desktop app share a newline-delimited JSON socket, but their names are not a one-to-one catalog: | CLI surface | Wire request | Current boundary | | -------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `get-answer` | `extract-md` | CLI-friendly name for query-anchored Markdown extraction. | | `auth-login` | `auth-login-key` | The CLI sends the raw API key; the app performs the device-bound exchange. | | No 0.2.0 CLI command | `extract-screen` | Current app protocol supports viewport/full plain screen extraction. Use [Monopty](/ai-clis/monopty) for a documented local headless screen command. | | No 0.2.0 CLI command | `ws-status`, `set-session`, token-form `auth-login` | Current app-internal protocol entries; they are not public parser commands in this payload. | | No 0.2.0 CLI command | `browser-open`, `browser-list`, `browser-navigate`, `browser-act`, `browser-status`, `browser-close` | Source-head app protocol for steering the visible Agent Browser tab; not part of the published CLI parser. | `command-list` is generated by the app, not by Clap. It currently includes 28 grouped entries, while the control request enum has 29 variants and the CLI has 19 operational commands. In particular, app dispatch implements `remote-auto-connect`, but the current grouped `command-list` omits it. Use root `--help` for the binary parser, `command-list` for current app access toggles, and source/gateway proof for remote exposure; none substitutes for the others. ### Source-head Agent Browser wire family Repository commit `7ca48fc1ba3e3266074a58c402b51955aa172b70` adds six app-control requests. They steer the same visible browser session the user is watching; they do not create a private headless browser: | Wire request | Input | Success contract | | ------------------ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `browser-open` | Optional `url` | Emits `agent-browser-open`; success reports `opened` and the requested URL. The frontend still owns tab mounting and session creation. | | `browser-list` | None | Returns live sessions with their id, URL, mode, and profile. Use the id for every request below. | | `browser-navigate` | `id`, `url` | Navigates one existing session and echoes the id and resulting target URL. | | `browser-act` | `id`, JSON string `action` | Runs the same action envelope as the frontend. Supported source kinds include `click`, `type`, `insert`, `key`, `mouse`, `viewport`, `wait`, and `eval`; MonoSurf read/write grants and the app entitlement gate still apply. | | `browser-status` | `id` | Returns the session's decoded URL, mode, and profile state. A malformed backend response fails instead of being passed through as success. | | `browser-close` | `id` | Closes one browser session and returns `closed: true`; the tab retains its own teardown path. | This family is compiled only with the app's `web` feature. A Base build returns `browser commands require the web plugin (app-monolex --features web)` for all six requests rather than an empty or synthetic success. The published `monolex-cli 0.2.0` payload has no parser verbs for constructing these messages, so the table documents the current app protocol, not six newly released CLI commands. All local socket requests except `command-list` honor the app's UI-managed disabled-command set. The Tauri `control_socket_query` bridge applies the same gate. Its current executable query map is `project-list`, `tab-list`, `status`, `gateway-info`, `command-list`, and `start-headless`. The Cloudflare `control_query_v1` allowlist contains additional names, but an allowlisted name still returns `unknown_query` unless this Tauri map implements it. A local CLI command is therefore not automatically web-callable. The six Agent Browser wire requests are not in this query map either. ## Automation Pattern ```bash theme={null} monolex-cli tab-new --provider codex --cwd "$PWD" --json monolex-cli tab-list --json # Select the newly observed .data.sessions[].id after it appears. SESSION_ID= monolex-cli write "$SESSION_ID" 'Explain this repository\r' monolex-cli wait-idle "$SESSION_ID" --idle-ms 800 --max-wait 60 monolex-cli get-answer "$SESSION_ID" 'Explain this repository' --json ``` `tab-new` returns an event-emission acknowledgement before the frontend creates the PTY, so poll `tab-list` and compute/select the newly observed id. Creating a tab, observing idle, and extracting an answer are three different proof layers. An idle terminal may still contain a prompt for more input, and a successful write does not prove that an AI CLI completed. ## Relationships | Tool | Ownership | | --------------------------------- | ---------------------------------------------------------------------------------------- | | Monolex desktop | Owns the Tauri app, visible tabs, viewer, and local control endpoint | | [Monopty](/ai-clis/monopty) | Controls local **headless** sessions and adds guarded/scenario workflows | | [Monosystem](/ai-clis/monosystem) | Owns cross-machine estate transport, daemon presence, and remote PTY control | | [OpenCLIs](/ai-clis/openclis) | Owns package discovery, install, update, and registry metadata beneath the tool commands |