---
icon: lucide/terminal
---

# CLI Reference

MindRoom provides a command-line interface for managing agents.

## Basic Usage

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

## Commands

<!-- CODE:START -->
<!-- from mindroom.cli 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]...

 MindRoom - AI agents that live in Matrix

 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                        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.                                    │
│ config    Manage MindRoom configuration files.                                         │
╰────────────────────────────────────────────────────────────────────────────────────────╯


```

<!-- OUTPUT:END -->

## version

Show the current MindRoom version.

<!-- CODE:START -->
<!-- from mindroom.cli 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          Show this message and exit.                                            │
╰────────────────────────────────────────────────────────────────────────────────────────╯


```

<!-- OUTPUT:END -->

## run

Start MindRoom with your configuration.

<!-- CODE:START -->
<!-- from mindroom.cli 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 dashboard API server (disable with --no-api)

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --log-level     -l              TEXT     Set the logging level (DEBUG, INFO, WARNING,  │
│                                          ERROR)                                        │
│                                          [default: INFO]                               │
│ --storage-path  -s              PATH     Base directory for persistent MindRoom data   │
│                                          (state, sessions, tracking)                   │
│                                          [default: mindroom_data]                      │
│ --api               --no-api             Start the dashboard API server alongside the  │
│                                          bot                                           │
│                                          [default: api]                                │
│ --api-port                      INTEGER  Port for the dashboard API server             │
│                                          [default: 8765]                               │
│ --api-host                      TEXT     Host for the dashboard API server             │
│                                          [default: 0.0.0.0]                            │
│ --help                                   Show this message and exit.                   │
╰────────────────────────────────────────────────────────────────────────────────────────╯


```

<!-- OUTPUT:END -->

## Examples

### Basic run

```bash
mindroom run
```

### Debug logging

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

### Custom storage path

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

### Show version

```bash
mindroom version
```
