# möbius CLI
`mobius-cli` is the reference Ratatui client for a `mobius-gateway`. The gateway owns Bot
profiles, providers, conversations, sandboxing, usage, routines, and swarms.
## Install the client
Download one `mobius-cli` archive and checksum from
[GitHub Releases](https://github.com/citizenhicks/mobius/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:
```sh
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:
```sh
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. Each run creates a chat for that Bot in the current directory. `/new` and
`/workspace <gateway-path>` open the Bot picker without changing other running chats. For a source
checkout, build both commands from the CLI package:
```sh
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:
```sh
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:
```sh
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, so create the
first gateway-host workspace chat from an Apple or local frontend.
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:
```sh
mobius-gateway exit
mobius-gateway connect
mobius pair tcp://127.0.0.1:8741 <one-time-code>
```
Run one task file without the TUI:
```sh
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:
```sh
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:
```sh
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`, `/new`, `/clear`, `/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 single saved-chat picker; it lists chats across every workspace.
The Nord-themed TUI uses the full terminal. The mouse wheel and Page Up/Page Down scroll the chat;
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.
Sandboxing runs on the gateway host and fails closed when its platform sandbox is unavailable.
## License
Licensed under [Apache-2.0](LICENSE). See [NOTICE](NOTICE) for upstream attribution.