# CLI Reference

MindRoom provides a command-line interface for managing agents.

## Basic Usage

```bash
mindroom [OPTIONS] COMMAND [ARGS]...
```

## Commands

<!-- CODE:START -->
<!-- from mindroom.cli.main import app -->
<!-- from typer.testing import CliRunner -->
<!-- runner = CliRunner() -->
<!-- result = runner.invoke(app, ["--help"]) -->
<!-- print("```") -->
<!-- print(result.output) -->
<!-- print("```") -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```

 Usage: root [OPTIONS] COMMAND [ARGS]...

 AI agents that live in Matrix and work everywhere via bridges.

 Quick start:
 mindroom config init   Create a starter config
 mindroom run           Start the system

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --install-completion            Install completion for the current shell.              │
│ --show-completion               Show completion for the current shell, to copy it or   │
│                                 customize the installation.                            │
│ --help                -h        Show this message and exit.                            │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ version             Show the current version of Mindroom.                              │
│ run                 Run the mindroom multi-agent system.                               │
│ doctor              Check your environment for common issues.                          │
│ connect             Pair this local MindRoom install with the hosted provisioning      │
│                     service.                                                           │
│ local-stack-setup   Start local Synapse + MindRoom Cinny using Docker only.            │
│ config              Manage MindRoom configuration files.                               │
│ avatars             Generate and sync managed avatar assets.                           │
│ threads             Export Matrix threads to local files.                              │
│ service             Install and manage MindRoom as a background user service.          │
╰────────────────────────────────────────────────────────────────────────────────────────╯


```

<!-- OUTPUT:END -->

## version

Show the current MindRoom version.

<!-- CODE:START -->
<!-- from mindroom.cli.main import app -->
<!-- from typer.testing import CliRunner -->
<!-- runner = CliRunner() -->
<!-- result = runner.invoke(app, ["version", "--help"]) -->
<!-- print("```") -->
<!-- print(result.output) -->
<!-- print("```") -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```

 Usage: root version [OPTIONS]

 Show the current version of Mindroom.

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                          │
╰────────────────────────────────────────────────────────────────────────────────────────╯


```

<!-- OUTPUT:END -->

## run

Start MindRoom with your configuration.

<!-- CODE:START -->
<!-- from mindroom.cli.main import app -->
<!-- from typer.testing import CliRunner -->
<!-- runner = CliRunner() -->
<!-- result = runner.invoke(app, ["run", "--help"]) -->
<!-- print("```") -->
<!-- print(result.output) -->
<!-- print("```") -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```

 Usage: root run [OPTIONS]

 Run the mindroom multi-agent system.

 This command starts the multi-agent bot system which automatically:
 - Creates all necessary user and agent accounts
 - Creates all rooms defined in config.yaml
 - Manages agent room memberships
 - Starts the bundled dashboard/API server (disable with --no-api)

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --log-level     -l              TEXT     Set the logging level (DEBUG, INFO, WARNING,  │
│                                          ERROR)                                        │
│                                          [env var: LOG_LEVEL]                          │
│                                          [default: INFO]                               │
│ --config        -c              PATH     Use this config file path. Defaults the       │
│                                          storage location to the selected config       │
│                                          directory unless --storage-path is set.       │
│ --storage-path  -s              PATH     Base directory for persistent MindRoom data   │
│                                          (state, sessions, tracking)                   │
│ --api               --no-api             Start the bundled dashboard/API server        │
│                                          alongside the bot                             │
│                                          [default: api]                                │
│ --api-port                      INTEGER  Port for the bundled dashboard/API server     │
│                                          [default: 8765]                               │
│ --api-host                      TEXT     Host for the bundled dashboard/API server     │
│                                          [default: 0.0.0.0]                            │
│ --help          -h                       Show this message and exit.                   │
╰────────────────────────────────────────────────────────────────────────────────────────╯


```

<!-- OUTPUT:END -->

## avatars

Generate and sync managed avatar assets.

<!-- CODE:START -->
<!-- from mindroom.cli.main import app -->
<!-- from typer.testing import CliRunner -->
<!-- runner = CliRunner() -->
<!-- result = runner.invoke(app, ["avatars", "--help"]) -->
<!-- print("```") -->
<!-- print(result.output) -->
<!-- print("```") -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```

 Usage: root avatars [OPTIONS] COMMAND [ARGS]...

 Generate and sync managed avatar assets.

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                          │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ generate   Generate missing managed avatar files in the workspace.                     │
│ sync       Sync configured room and root-space avatars to Matrix using the initialized │
│            router account.                                                             │
╰────────────────────────────────────────────────────────────────────────────────────────╯


```

<!-- OUTPUT:END -->

## avatars generate

Generate missing managed avatar files in the workspace.
In a source checkout, generated files are written under `./avatars/`.
In containerized deployments, generated overrides are written under the persistent MindRoom storage path.
Existing managed files are skipped by default.
Use `--force` to overwrite them after changing avatar prompts or styles.

<!-- CODE:START -->
<!-- from mindroom.cli.main import app -->
<!-- from typer.testing import CliRunner -->
<!-- runner = CliRunner() -->
<!-- result = runner.invoke(app, ["avatars", "generate", "--help"]) -->
<!-- print("```") -->
<!-- print(result.output) -->
<!-- print("```") -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```

 Usage: root avatars generate [OPTIONS]

 Generate missing managed avatar files in the workspace.

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --force            Overwrite existing managed workspace avatar files.                  │
│ --help   -h        Show this message and exit.                                         │
╰────────────────────────────────────────────────────────────────────────────────────────╯


```

<!-- OUTPUT:END -->

## avatars sync

Sync configured room and root-space avatars to Matrix using the initialized router account.
Existing Matrix avatars are skipped by default.
Use `--force` to replace them.

<!-- CODE:START -->
<!-- from mindroom.cli.main import app -->
<!-- from typer.testing import CliRunner -->
<!-- runner = CliRunner() -->
<!-- result = runner.invoke(app, ["avatars", "sync", "--help"]) -->
<!-- print("```") -->
<!-- print(result.output) -->
<!-- print("```") -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```

 Usage: root avatars sync [OPTIONS]

 Sync configured room and root-space avatars to Matrix using the initialized router
 account.

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --force            Replace existing Matrix room and root-space avatars.                │
│ --help   -h        Show this message and exit.                                         │
╰────────────────────────────────────────────────────────────────────────────────────────╯


```

<!-- OUTPUT:END -->

## threads

Export Matrix threads to local files.

<!-- CODE:START -->
<!-- from mindroom.cli.main import app -->
<!-- from typer.testing import CliRunner -->
<!-- runner = CliRunner() -->
<!-- result = runner.invoke(app, ["threads", "--help"]) -->
<!-- print("```") -->
<!-- print(result.output) -->
<!-- print("```") -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```

 Usage: root threads [OPTIONS] COMMAND [ARGS]...

 Export Matrix threads to local files.

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                          │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ export   Export Matrix threads to YAML files for grep/ripgrep search.                  │
╰────────────────────────────────────────────────────────────────────────────────────────╯


```

<!-- OUTPUT:END -->

## threads export

Export Matrix threads to YAML files for grep/ripgrep search.
The command reads persisted Matrix accounts and rooms from `matrix_state.yaml`, so run MindRoom once before exporting.
By default it writes to `<storage>/thread_exports`.

<!-- CODE:START -->
<!-- from mindroom.cli.main import app -->
<!-- from typer.testing import CliRunner -->
<!-- runner = CliRunner() -->
<!-- result = runner.invoke(app, ["threads", "export", "--help"]) -->
<!-- print("```") -->
<!-- print(result.output) -->
<!-- print("```") -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```

 Usage: root threads export [OPTIONS]

 Export Matrix threads to YAML files for grep/ripgrep search.

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --config            -c      PATH     Use this config file path.                        │
│ --storage-path      -s      PATH     Base directory for persistent MindRoom data.      │
│ --output            -o      PATH     Output directory. Defaults to                     │
│                                      <storage>/thread_exports.                         │
│ --room              -r      TEXT     Filter exported rooms by a substring of the room  │
│                                      key, alias, name, or Matrix room ID.              │
│ --watch                              Repeat the export forever on a fixed interval.    │
│ --interval                  INTEGER  Watch interval in seconds. [default: 300]         │
│ --max-thread-roots          INTEGER  Maximum thread roots to enumerate per room.       │
│                                      [default: 2000]                                   │
│ --help              -h               Show this message and exit.                       │
╰────────────────────────────────────────────────────────────────────────────────────────╯


```

<!-- OUTPUT:END -->

```bash
mindroom threads export --storage-path mindroom_data --output /tmp/mindroom-thread-exports
mindroom threads export --storage-path mindroom_data --room lobby
mindroom threads export --storage-path mindroom_data --watch --interval 300
```

## service

Install and manage MindRoom as a background user service.
MindRoom runs through `uv tool run` and starts automatically at login.
On macOS, MindRoom uses launchd user agents.
On Linux, MindRoom uses systemd user services.

<!-- CODE:START -->
<!-- from mindroom.cli.main import app -->
<!-- from typer.testing import CliRunner -->
<!-- runner = CliRunner() -->
<!-- result = runner.invoke(app, ["service", "--help"]) -->
<!-- print("```") -->
<!-- print(result.output) -->
<!-- print("```") -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```

 Usage: root service [OPTIONS] COMMAND [ARGS]...

 Install and manage MindRoom as a background user service.

 MindRoom runs through `uv tool run` and starts automatically at login.

 Supported platforms:
 - macOS: launchd (`~/Library/LaunchAgents/`)
 - Linux: systemd user services (`~/.config/systemd/user/`)

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                          │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ install     Install and start MindRoom as a background user service.                   │
│ uninstall   Stop and remove the MindRoom user service.                                 │
│ start       Start the installed MindRoom user service.                                 │
│ stop        Stop the installed MindRoom user service without removing it.              │
│ restart     Restart the installed MindRoom user service.                               │
│ status      Show MindRoom service status and recent logs.                              │
│ logs        Follow MindRoom service logs.                                              │
╰────────────────────────────────────────────────────────────────────────────────────────╯


```

<!-- OUTPUT:END -->

### service install

Install and start MindRoom as a background user service.
Use `--no-confirm` for non-interactive setup.

<!-- CODE:START -->
<!-- from mindroom.cli.main import app -->
<!-- from typer.testing import CliRunner -->
<!-- runner = CliRunner() -->
<!-- result = runner.invoke(app, ["service", "install", "--help"]) -->
<!-- print("```") -->
<!-- print(result.output) -->
<!-- print("```") -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```

 Usage: root service install [OPTIONS]

 Install and start MindRoom as a background user service.

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --skip-deps             Skip uv dependency check.                                      │
│ --no-confirm  -y        Skip confirmation prompts.                                     │
│ --help        -h        Show this message and exit.                                    │
╰────────────────────────────────────────────────────────────────────────────────────────╯


```

<!-- OUTPUT:END -->

### service status

Show MindRoom service status and recent logs.

<!-- CODE:START -->
<!-- from mindroom.cli.main import app -->
<!-- from typer.testing import CliRunner -->
<!-- runner = CliRunner() -->
<!-- result = runner.invoke(app, ["service", "status", "--help"]) -->
<!-- print("```") -->
<!-- print(result.output) -->
<!-- print("```") -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```

 Usage: root service status [OPTIONS]

 Show MindRoom service status and recent logs.

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --logs  -l      INTEGER  Number of recent log lines to show. Use 0 to hide logs.       │
│                          [default: 10]                                                 │
│ --help  -h               Show this message and exit.                                   │
╰────────────────────────────────────────────────────────────────────────────────────────╯


```

<!-- OUTPUT:END -->

### service uninstall

Stop and remove the MindRoom user service.
On macOS, log files are preserved under `~/Library/Logs/mindroom/`.

<!-- CODE:START -->
<!-- from mindroom.cli.main import app -->
<!-- from typer.testing import CliRunner -->
<!-- runner = CliRunner() -->
<!-- result = runner.invoke(app, ["service", "uninstall", "--help"]) -->
<!-- print("```") -->
<!-- print(result.output) -->
<!-- print("```") -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```

 Usage: root service uninstall [OPTIONS]

 Stop and remove the MindRoom user service.

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --no-confirm  -y        Skip confirmation prompts.                                     │
│ --help        -h        Show this message and exit.                                    │
╰────────────────────────────────────────────────────────────────────────────────────────╯


```

<!-- OUTPUT:END -->

## doctor

Check your environment for common issues before running `mindroom run`.

Runs a series of checks in one pass:

- **Config file** exists and is valid YAML with correct Pydantic schema
- **Providers** — validates API keys for each configured provider (Anthropic, OpenAI, Ollama, Vertex AI Claude, etc.)
- **Memory config** — checks memory LLM and embedder reachability (Ollama, OpenAI embeddings, sentence-transformers)
- **Matrix homeserver** — verifies the homeserver is reachable via `/_matrix/client/versions`
- **Storage** — confirms the storage directory is writable

<!-- CODE:START -->
<!-- from mindroom.cli.main import app -->
<!-- from typer.testing import CliRunner -->
<!-- runner = CliRunner() -->
<!-- result = runner.invoke(app, ["doctor", "--help"]) -->
<!-- print("```") -->
<!-- print(result.output) -->
<!-- print("```") -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```

 Usage: root doctor [OPTIONS]

 Check your environment for common issues.

 Runs connectivity, configuration, and credential checks in a single pass
 so you can fix everything before running `mindroom run`.

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                          │
╰────────────────────────────────────────────────────────────────────────────────────────╯


```

<!-- OUTPUT:END -->

## config

Manage MindRoom configuration files.
The `config` subgroup contains commands for creating, viewing, editing, and validating your `config.yaml`.

<!-- CODE:START -->
<!-- from mindroom.cli.main import app -->
<!-- from typer.testing import CliRunner -->
<!-- runner = CliRunner() -->
<!-- result = runner.invoke(app, ["config", "--help"]) -->
<!-- print("```") -->
<!-- print(result.output) -->
<!-- print("```") -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```

 Usage: root config [OPTIONS] COMMAND [ARGS]...

 Manage MindRoom configuration files.

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                          │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ init       Create a starter config.yaml with example agents and models.                │
│ show       Display the current config file with syntax highlighting.                   │
│ edit       Open config.yaml in your default editor.                                    │
│ validate   Validate config.yaml and check for common issues.                           │
│ path       Show the resolved config file path and search locations.                    │
│ migrate    Apply safe, text-preserving migrations to config.yaml.                      │
╰────────────────────────────────────────────────────────────────────────────────────────╯


```

<!-- OUTPUT:END -->

### config init

Create a starter `config.yaml` with example agents, models, memory, and sensible defaults.

Matrix server presets (`--matrix-server`) choose where MindRoom should create Matrix users and rooms: `mindroom.chat` (default hosted Matrix) or `self-hosted` (your own homeserver).
Provider presets (`--provider`) set the default model: `anthropic`, `codex`, `llama.cpp`, `ollama`, `openai`, `openrouter`, or `vertexai_claude`.
Generated configs include commented model alternatives for providers that have common variants, such as OpenAI mini/nano models.

```bash
# Hosted Matrix quickstart (creates ~/.mindroom/config.yaml)
mindroom config init

# Self-hosted Matrix with Anthropic
mindroom config init --matrix-server self-hosted --provider anthropic

# Hosted Matrix with Codex CLI ChatGPT subscription auth
mindroom config init --matrix-server mindroom.chat --provider codex

# Hosted Matrix with Ollama
mindroom config init --matrix-server mindroom.chat --provider ollama

# Hosted Matrix with llama.cpp
mindroom config init --matrix-server mindroom.chat --provider llama.cpp

# Hosted Matrix with Vertex AI Claude
mindroom config init --matrix-server mindroom.chat --provider vertexai_claude

# Preview generated YAML without writing files
mindroom config init --matrix-server mindroom.chat --provider ollama --print

# Force overwrite existing config
mindroom config init --force
```

Use `--print` to preview the generated `config.yaml` in the terminal with YAML syntax highlighting.
It does not create or modify `config.yaml`, `.env`, or starter workspace files.

The `--provider codex` preset generates `provider: codex` with `id: gpt-5.5` and `context_window: 258000`.
They set `extra_kwargs.reasoning_effort: medium`.
Prompt caching is enabled automatically per active agent session; leave `prompt_cache_key` unset unless you intentionally want to override the derived key.
Run `codex login` first so MindRoom can read `~/.codex/auth.json`.

The `--provider ollama` preset generates `provider: ollama` with `id: gemma4`, an additional `qwen3_6_27b` model using `qwen3.6:27b`, and `OLLAMA_HOST=http://localhost:11434`.
Pull both local models before running MindRoom:

```bash
ollama pull gemma4
ollama pull qwen3.6:27b
```

The `--provider llama.cpp` preset generates OpenAI-compatible local server config for Unsloth GGUF models.
Start llama.cpp with one of the configured model refs before running MindRoom:

```bash
llama-server -hf unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q4_K_M --host 127.0.0.1 --port 8080
llama-server -hf unsloth/Qwen3.6-27B-GGUF:UD-Q4_K_XL --host 127.0.0.1 --port 8080
```

### config show

Display the current config file with syntax highlighting.

```bash
# Show config with syntax highlighting
mindroom config show

# Print raw YAML (useful for piping)
mindroom config show --raw

# Show config at a specific path
mindroom config show --path /custom/path/config.yaml
```

### config edit

Open `config.yaml` in your default editor.
Editor preference: `$EDITOR` → `$VISUAL` → `nano` → `vim` → `vi`.

```bash
mindroom config edit
```

### config validate

Validate `config.yaml` and check for common issues.
Parses the YAML config using Pydantic and reports errors in a friendly format.
Also checks whether required API keys are set as environment variables.

```bash
mindroom config validate
```

### config path

Show the resolved config file path and all search locations.

```bash
mindroom config path
```

## connect

Pair this local MindRoom install with a provisioning service.

Default provisioning URL is `https://mindroom.chat` unless you override it with `--provisioning-url` or `MINDROOM_PROVISIONING_URL`.

```bash
mindroom connect --pair-code ABCD-EFGH
```

On success (default `--persist-env`), this writes to `.env` next to `config.yaml`:

- `MINDROOM_PROVISIONING_URL`
- `MINDROOM_LOCAL_CLIENT_ID`
- `MINDROOM_LOCAL_CLIENT_SECRET`
- `MINDROOM_NAMESPACE`

If your config still contains the owner placeholder token `__MINDROOM_OWNER_USER_ID_FROM_PAIRING__`, `connect` will auto-replace it when pairing returns a valid `owner_user_id`.

Use `--no-persist-env` if you want to export variables only for the current shell session.

```bash
mindroom connect --pair-code ABCD-EFGH --no-persist-env
```

Use `--provisioning-url` for non-default deployments:

```bash
mindroom connect \
  --pair-code ABCD-EFGH \
  --provisioning-url https://matrix.example.com
```

## local-stack-setup

Start local Synapse and the MindRoom Cinny client container for development.

By default this command also writes `MATRIX_HOMESERVER`, `MATRIX_SERVER_NAME`, and `MATRIX_SSL_VERIFY=false` into `.env` next to your active `config.yaml` so `mindroom run` works without inline env exports.

<!-- CODE:START -->
<!-- from mindroom.cli.main import app -->
<!-- from typer.testing import CliRunner -->
<!-- runner = CliRunner() -->
<!-- result = runner.invoke(app, ["local-stack-setup", "--help"]) -->
<!-- print("```") -->
<!-- print(result.output) -->
<!-- print("```") -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```

 Usage: root local-stack-setup [OPTIONS]

 Start local Synapse + MindRoom Cinny using Docker only.

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --synapse-dir                                 PATH                 Directory           │
│                                                                    containing Synapse  │
│                                                                    docker-compose.yml  │
│                                                                    (from               │
│                                                                    mindroom-stack      │
│                                                                    settings).          │
│                                                                    [default:           │
│                                                                    local/matrix]       │
│ --homeserver-url                              TEXT                 Homeserver URL that │
│                                                                    Cinny and MindRoom  │
│                                                                    should use.         │
│                                                                    [default:           │
│                                                                    http://localhost:8… │
│ --server-name                                 TEXT                 Matrix server name  │
│                                                                    (default: inferred  │
│                                                                    from                │
│                                                                    --homeserver-url    │
│                                                                    hostname).          │
│ --cinny-port                                  INTEGER RANGE        Local host port for │
│                                               [1<=x<=65535]        the MindRoom Cinny  │
│                                                                    container.          │
│                                                                    [default: 8080]     │
│ --cinny-image                                 TEXT                 Docker image for    │
│                                                                    MindRoom Cinny.     │
│                                                                    [default:           │
│                                                                    ghcr.io/mindroom-a… │
│ --cinny-container-n…                          TEXT                 Container name for  │
│                                                                    MindRoom Cinny.     │
│                                                                    [default:           │
│                                                                    mindroom-cinny-loc… │
│ --skip-synapse                                                     Skip starting       │
│                                                                    Synapse (assume it  │
│                                                                    is already          │
│                                                                    running).           │
│ --persist-env             --no-persist-env                         Persist Matrix      │
│                                                                    local dev settings  │
│                                                                    to .env next to     │
│                                                                    config.yaml.        │
│                                                                    [default:           │
│                                                                    persist-env]        │
│ --help                -h                                           Show this message   │
│                                                                    and exit.           │
╰────────────────────────────────────────────────────────────────────────────────────────╯


```

<!-- OUTPUT:END -->

## Examples

### Basic run

```bash
mindroom run
```

### Debug logging

```bash
mindroom run --log-level DEBUG
```

To debug MindRoom internals without enabling debug logs from every dependency, keep the global level at `INFO` and set targeted logger overrides:

```bash
LOG_LEVEL=INFO MINDROOM_LOGGER_LEVELS="mindroom:DEBUG,httpx:WARNING,httpcore:WARNING,anthropic:INFO,nio:WARNING" mindroom run
```

Matrix crypto decrypt warnings from `nio.crypto` are quieted by default because missing Megolm sessions can produce bursts of diagnostically useful but high-volume logs.
To inspect those warnings while debugging encryption state, explicitly restore that logger:

```bash
LOG_LEVEL=INFO MINDROOM_LOGGER_LEVELS="nio.crypto:WARNING" mindroom run
```

### Custom storage path

```bash
mindroom run --storage-path /data/mindroom
```

### Pair local install with hosted provisioning

```bash
mindroom connect --pair-code ABCD-EFGH
```

### Start local Synapse + Cinny (default local setup)

```bash
mindroom local-stack-setup --synapse-dir /path/to/mindroom-stack/local/matrix
```

### Start local stack without writing `.env`

```bash
mindroom local-stack-setup --no-persist-env
```

### Show version

```bash
mindroom version
```

### Preflight environment check

```bash
mindroom doctor
```

### Initialize a config

```bash
mindroom config init
```

### Validate your config

```bash
mindroom config validate
```
