CLI Reference
MindRoom provides a command-line interface for managing agents.
Basic Usage
Commands
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. │
│ service Install and manage MindRoom as a background user service. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
version
Show the current MindRoom version.
Usage: root version [OPTIONS]
Show the current version of Mindroom.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
run
Start MindRoom with your configuration.
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] │
│ --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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
avatars
Generate and sync managed avatar assets.
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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
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.
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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
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.
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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
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.
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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
service install
Install and start MindRoom as a background user service.
Use --no-confirm for non-interactive setup.
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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
service status
Show MindRoom service status and recent logs.
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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
service uninstall
Stop and remove the MindRoom user service.
On macOS, log files are preserved under ~/Library/Logs/mindroom/.
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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
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
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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
config
Manage MindRoom configuration files.
The config subgroup contains commands for creating, viewing, editing, and validating your config.yaml.
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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
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.
# 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:
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:
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.
# 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.
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.
config path
Show the resolved config file path and all search locations.
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.
On success (default --persist-env), this writes to .env next to config.yaml:
MINDROOM_PROVISIONING_URLMINDROOM_LOCAL_CLIENT_IDMINDROOM_LOCAL_CLIENT_SECRETMINDROOM_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.
Use --provisioning-url for non-default deployments:
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.
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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
Examples
Basic run
Debug logging
To debug MindRoom internals without enabling debug logs from every dependency, keep the global level at INFO and set targeted logger overrides:
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: