möbius CLI

mobius-cli is the reference Ratatui client for a mobius-gateway. The gateway owns Bot profiles, providers, chats, sandboxing, usage, and routines.

Install the client

Download one mobius-cli archive and checksum from GitHub Releases:

• Apple Silicon macOS: aarch64-apple-darwin
• x86_64 Linux: x86_64-unknown-linux-gnu

Verify with shasum -a 256 -c FILE.sha256, extract the included mobius and mobius-gateway binaries into one directory, and put it on your PATH. Rust users and other macOS or Linux architectures can install both commands with Rust 1.98 or newer:

cargo install --locked mobius-cli

Gateway included

The CLI package installs its gateway beside mobius; the core mobius crate is linked into the binaries. Run the CLI from the workspace for the chat you want to create:

cd /path/to/repository
mobius

With no explicit gateway endpoint or token, the first run initializes the machine-wide default gateway with both a loopback listener and Cloudflare Quick Tunnel, provisions the CLI's local credential, and starts mobius-gateway in the background. A later mobius-gateway connect advertises the local TCP and public WSS endpoints with one pairing code that works through either endpoint. On an empty gateway, plain mobius opens provider setup; the gateway then creates the default Mobius Bot. A new local workspace opens the Bot picker; choose a Bot and press Enter to start. /new and /workspace <gateway-path> open the same picker later. For a source checkout, build both commands from the CLI package:

cargo build -p mobius-cli
cargo run -p mobius-cli --bin mobius

Plaintext is restricted to loopback. A gateway reachable over the network must use a publicly trusted TLS certificate matching its public hostname. Initialize it once, then run the supervised connection flow while the gateway is stopped:

mobius-gateway init --listen 0.0.0.0:8741 \
  --tls-cert /absolute/path/fullchain.pem \
  --tls-key /absolute/path/private-key.pem
mobius-gateway connect --endpoint tls://gateway.example:8741

Then use the endpoint and one-time code it displays on the client machine:

mobius pair tls://gateway.example:8741 <one-time-code>
mobius

mobius pair saves and selects the endpoint together with the token returned by the gateway; no environment variable is needed. A remote terminal opens an existing gateway chat or, on an empty gateway, starts one in the gateway's current directory after Bot selection. If the gateway is already running, create another code with /pair from an authenticated terminal or Gateway → Pair another device in an Apple client.

If local state already exists without a saved CLI token, stop the gateway and run the supervised pairing flow in another terminal:

mobius-gateway exit
mobius-gateway connect
mobius pair tcp://127.0.0.1:8741 <one-time-code>

Run one task file without the TUI:

mobius run @builder path/to/task.md
# From a source checkout:
cargo run -p mobius-cli --bin mobius -- run @builder path/to/task.md

mobius run is noninteractive and never creates or configures a Bot. Run plain mobius in a terminal first when the gateway has no Bots.

The selected conversation workspace—not the CLI process—is the command and file boundary. An approval prompt aborts a headless run, so a Bot routine that edits files or runs commands needs an appropriate Bot approval policy.

Manage the gateway extension catalog without creating or opening a chat:

mobius extensions

The same lifecycle screen is available as /extensions from an idle chat. Installation accepts an HTTPS Git URL or a GitHub tree URL; update, uninstall, and digest-bound hook trust operate on the selected installed extension.

/login is the single provider setup path. It opens the guided provider screen, where API keys can be pasted into a masked field, the environment variable declared by the provider manifest is used when the field is empty, and device-login providers show their login flow. There is no separate environment-name setting. Setup covers the built-in manifests compiled into both the gateway and CLI; injected ModelRouter entries are library-only. The final page confirms the provider's model and reasoning choice and updates the Bot that owns the current chat. /bot opens the same Bot-owned capability and approval-policy editor without creating per-chat configuration. Required gateway capabilities remain visible but cannot be deselected. Secrets are sent directly to the gateway and never returned to the CLI. /gateway lists saved endpoints and opens a second page to pair a new endpoint; reconnect and delete act on the selected saved gateway. Explicit endpoint or token environment variables make that screen read-only until they are unset.

API-key providers use their standard environment variables:

export OPENAI_API_KEY=...
export MOONSHOT_API_KEY=...
export OPENROUTER_API_KEY=...
export ANTHROPIC_API_KEY=...

The CLI stores only an owner-readable selected endpoint and endpoint-token map at ~/.mobius/gateway-tokens.json. MOBIUS_GATEWAY_TOKEN overrides the saved token explicitly; MOBIUS_GATEWAY_TOKEN_FILE changes the account-file path.

Terminal contributions

The TUI is a thin subscriber to the framework capability catalog:

• Capabilities own their commands, status widgets, references, and capability-specific rendering.
• / opens both CLI shell commands and commands contributed by framework capabilities.
• $ references are contributed by the Extensions middleware.
• @ workspace-file completion is available for a local plaintext gateway; TLS gateways do not scan similarly named paths on the client machine.

The CLI owns only shell lifecycle and presentation commands: /help, /gateway, /extensions, /bot, /login, /pair, /profile, /events, /new, /clear, /rename, /pin, /unpin, /reassign, /attach, /delete, /files, /diff, /branch, /queued, /status, /interrupt, and /exit. Capabilities contribute commands such as /artifacts, so the menu changes with the installed gateway capabilities. The gateway always contributes /resume as the saved-chat picker; it lists chats across every workspace. Bot → Conversations opens the same chats grouped by Bot.

The Nord-themed TUI uses the full terminal. Type in any picker to filter it. The mouse wheel and Page Up/Page Down scroll the chat; Page Up at the oldest loaded event fetches earlier history. Ctrl-T opens a full-screen transcript view, releases mouse capture for native drag-to-copy, and scrolls with Arrow or Page Up/Page Down. Up/Down and Ctrl-P/Ctrl-N navigate composer history. /files downloads the selected chat file without overwriting an existing local file; Delete in the file picker removes it from the gateway after confirmation.

/diff [unstaged|staged|committed] opens a full-screen diff browser. The left pane lists changed files; the right pane shows the selected file with syntax highlighting, old/new line numbers, and red/green changes. Tab switches panes, Up/Down or J/K navigate, Page Up/Page Down scroll a page, Left/Right scroll long lines without wrapping, and [/] jump between hunks. Click a file to select it, or use the mouse wheel over either pane. Narrow terminals show the focused pane only. Esc returns to the chat without changing the draft. Mouse capture stays on in this browser; use your terminal's selection modifier for native drag-to-copy.

Sandboxing runs on the gateway host and fails closed when its platform sandbox is unavailable.

License

Licensed under Apache-2.0. See NOTICE for upstream attribution.