CLI Reference
This page lists every mindroom command with its options and links to the page that explains each feature in depth.
Start with mindroom run, which sets up, pairs, and starts MindRoom on first use, or use mindroom config init to create the configuration without starting.
Every command also prints its options with --help.
Commands
Usage: root [OPTIONS] COMMAND [ARGS]...
AI agents that live in Matrix and work everywhere via bridges.
Quick start:
mindroom run Set up on first run, pair, and start
mindroom config init Create a starter config without starting
╭─ 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 ─────────────────────────────────────────────────────────────────────────────╮
│ check-active-responses Check live work; exit 0 idle, 1 busy, or 2 unavailable. │
│ debug-report Collect everything the backend stored about a reported │
│ conversation, as JSON. │
│ version Show the current version of Mindroom. │
│ run Run the mindroom multi-agent system. │
│ doctor Check your environment for common issues. │
│ connect Connect this local MindRoom to your MindRoom Chat account by │
│ approving a link. │
│ local-stack-setup Start local Synapse + MindRoom Chat using Docker only. │
│ config Manage MindRoom configuration files. │
│ plugins Validate and vendor external MindRoom plugins. │
│ desktop Connect allowlisted local apps, read-only folders, and │
│ locally approved shell commands to cloud MindRoom over Matrix │
│ E2EE. │
│ avatars Generate and sync managed avatar assets. │
│ threads Export Matrix threads to local files. │
│ journal Inspect and rebind the durable event journal. │
│ service Install and manage MindRoom as a background user service. │
│ trigger Send signed external triggers. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
run
Start MindRoom with your configuration.
On first run in a terminal, mindroom run creates the hosted starter config, pairs with MindRoom Chat, and offers to install the login service.
See Getting Started for the setup questions and for unattended setup with --provider and --service.
An interactive terminal that nobody answers waits at the first prompt, so unattended runs should set MINDROOM_CONFIG_TEMPLATE or create the config first with mindroom config init --no-input.
On a hosted install, the dashboard becomes available after pairing is approved.
.env is read only at startup, so restart mindroom run after editing it.
Usage: root run [OPTIONS]
Run the mindroom multi-agent system.
This command starts the multi-agent bot system which automatically:
- Creates a hosted starter config on first run in a terminal, or with --provider
- Pairs hosted installs with your MindRoom Chat account on first run
- Offers on first run to keep running as a background service that starts at login
(--service/--no-service)
- 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) │
│ --bootstrap-config-bundle PATH Initialize the selected │
│ config directory from this │
│ bundle only when the │
│ directory is absent. │
│ --bootstrap-config-bundle-r… TEXT Install a changed bootstrap │
│ revision through native │
│ validation; preserve a │
│ matching active revision. │
│ --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] │
│ --provider TEXT Model provider preset for │
│ the starter config when │
│ none exists, with the │
│ choices of `config init │
│ --provider`. It also lets │
│ setup run without a │
│ terminal, taking the API │
│ key from the environment. │
│ --service --no-service After setup and pairing, │
│ install and start MindRoom │
│ as a login service (systemd │
│ or launchd) instead of │
│ running it here, or never │
│ offer to. A first run in a │
│ terminal asks. │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
Debug logging
--log-level DEBUG also enables debug logs from most dependencies, but Matrix nio loggers stay at WARNING unless you override them with MINDROOM_LOGGER_LEVELS.
To debug MindRoom alone, keep the global level at INFO and set per-logger overrides with MINDROOM_LOGGER_LEVELS:
LOG_LEVEL=INFO MINDROOM_LOGGER_LEVELS="mindroom:DEBUG,httpx:WARNING,httpcore:WARNING,anthropic:INFO,nio:WARNING" mindroom run
Matrix decrypt warnings from nio.crypto are hidden by default; add nio.crypto:WARNING to MINDROOM_LOGGER_LEVELS to see them while debugging encryption.
config
Create, view, edit, and validate 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 a personal agent and model. │
│ 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. │
│ resolve Print the fully merged config YAML with all !include tags resolved. │
│ path Show the resolved config file path and search locations. │
│ use-local-model Use a local model as the default, keeping explicitly selected agent │
│ models. │
│ migrate Migrate config.yaml to membership access settings. │
│ fingerprint Print the config source SHA-256, including all transitively included │
│ files. │
│ install-bundle Validate and install a complete tree; use check-applied to confirm │
│ runtime reload. │
│ classify-change Classify tree differences; exit 0 YAML/include sources only, 1 other │
│ changes, 2 error. │
│ apply-bundle Hot-apply a source-only tree change; exit 0 applied, 1 pending, 2 │
│ failed, 3 rolled back, 4 unconfirmed, 5 restart. │
│ check-applied Confirm config application; exit 0 applied, 1 pending/mismatch, 2 │
│ failed/restart-required/unavailable. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
config init
Create a starter config.yaml and .env with the personal Mind agent, starter models, file-based memory, and sensible defaults.
For hosted MindRoom Chat, mindroom run runs this setup interactively on first run, so use config init to choose presets up front, use a self-hosted homeserver, or create files without starting.
| Option | Effect |
|---|---|
--path, -p |
Where to write config.yaml; .env goes in the same directory. Defaults to the auto-detected location, usually ~/.mindroom/config.yaml. |
--matrix-server |
Where MindRoom creates Matrix users and rooms: mindroom.chat (hosted, default) or self-hosted (your own homeserver). |
--provider |
Default model provider: anthropic, azure, bedrock_claude, codex, kimi, llama.cpp, ollama, openai, openrouter, or vertexai_claude; defaults to openai, except that self-hosted in a terminal asks. |
--print |
Print the generated config.yaml with syntax highlighting without writing config.yaml, .env, or starter workspace files. |
--no-input |
Never prompt: keep an existing config.yaml unchanged, create anything missing, and use openai unless --provider is given. |
--force |
Overwrite without asking: replaces config.yaml, .env (including API keys and pairing credentials), the Mind starter workspace files such as MEMORY.md and USER.md, and the AGENTS.md beside the config; back up anything you want to keep first. |
Generated configs include commented model alternatives for providers with common variants, such as other OpenAI model tiers.
# Hosted Matrix quickstart (creates ~/.mindroom/config.yaml)
mindroom config init
# Create a config for a separate instance directory
mindroom config init --path ./instance/config.yaml
# Self-hosted Matrix with Anthropic
mindroom config init --matrix-server self-hosted --provider anthropic
# Preview generated YAML without writing files
mindroom config init --provider ollama --print
# Regenerate config.yaml, .env, and starter workspace files from scratch
mindroom config init --force
Some presets need a local login or server before MindRoom can answer:
codex: runcodex loginfirst; see Codex Models for the generated models.kimi: runkimiand/loginfirst; see Kimi Models.ollama: generatesgemma4asdefaultandqwen3.8:27basqwen3_8_27b, withOLLAMA_HOST=http://localhost:11434; pull both models first withollama pull gemma4andollama pull qwen3.8:27b.llama.cpp: generates Unsloth GGUF models for a llama.cpp server athttp://localhost:8080/v1; start it with one of the configured model refs:
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.8-27B-GGUF:UD-Q4_K_XL --host 127.0.0.1 --port 8080
config show
Display the current config file with syntax highlighting.
mindroom config show
mindroom config show --raw # plain YAML for piping
mindroom config show --path /custom/path/config.yaml
config edit
Open config.yaml in your editor, chosen from $EDITOR, then $VISUAL, then nano, vim, or vi.
config validate
Check config.yaml against the schema, report errors readably, and warn about missing provider API keys.
config path
Show the resolved config file path and every search location.
config resolve
Print the fully merged YAML with every !include resolved and keys sorted, so you can diff the result before and after splitting a configuration into include files.
config migrate
Convert a config that still uses retired access fields to the membership access settings, or print No migrations applied. when nothing needs to change.
See Membership Access Migration for when to run it.
Config bundle commands
config fingerprint, config install-bundle, config classify-change, config apply-bundle, and config check-applied install and confirm complete configuration trees; see Config Bundles.
doctor
Check your environment for common issues before running mindroom run.
It checks, in one pass:
- Config file: exists, is valid YAML, and matches the config schema.
- Providers: API keys for each configured provider (Anthropic, OpenAI, Ollama, Vertex AI Claude, and others) are valid.
- Memory config: the memory LLM and embedder are reachable (Ollama, OpenAI embeddings, sentence-transformers).
- Matrix homeserver: the homeserver answers
/_matrix/client/versions. - Pairing: on hosted installs, whether this machine is paired with MindRoom Chat; before the first run it passes with
Not paired yet, becausemindroom runpairs automatically. - Storage: the storage directory is writable.
- Encryption stores: persisted Matrix device identities still have their local encryption stores.
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 ──────────────────────────────────────────────────────────────────────────────╮
│ --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) │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
connect
Pair this machine with your MindRoom Chat account without starting MindRoom; mindroom run pairs automatically.
See connect on the Hosted Matrix page for options, approval, and saved credentials.
service
Install and manage MindRoom as a background user service that starts at login, using launchd user agents on macOS and systemd user services on Linux.
The service runs the MindRoom version that installed it, so rerun mindroom service install after upgrading.
Installing also installs that version as a uv tool, which puts a mindroom executable in uv's tool directory (usually ~/.local/bin).
From a source checkout with commits past a release, this replaces an installed mindroom uv tool, including an editable one, with that release.
On a headless Linux machine, run loginctl enable-linger so the service keeps running after you log out.
The service does not see your shell's environment, so mindroom service install and mindroom run --service first save MINDROOM_API_KEY and any provider API keys exported in your shell (such as OPENAI_API_KEY or OPENAI_API_KEY_FILE) to .env.
Installation stops with Refusing to write <KEY> to the env file when an exported value cannot be stored in .env unchanged, for example because it contains ${.
When the installed service would serve the dashboard without a credential, installing prints the open-dashboard warning in the terminal.
After editing .env, run mindroom service restart.
On first run in a terminal, a plain mindroom run offers to install the service after pairing; answering yes starts the service instead of running MindRoom in that terminal, and a failed installation falls back to the terminal.
The offer is skipped when a MindRoom service is already installed, when systemd is not running (for example in containers), with --no-service, and when run was given --config, --storage-path, --no-api, --api-host, or --api-port, because the service runs a plain mindroom run.
To install later, run mindroom service install or mindroom run --service.
mindroom run --service installs without asking, replaces an installed service, refuses those options, and exits with an error when the service cannot be installed.
Usage: root service [OPTIONS] COMMAND [ARGS]...
Install and manage MindRoom as a background user service.
MindRoom runs the version installed by this command through `uv tool run` and starts
automatically at login.
That version is also installed as a uv tool, so the service runs from a persistent
environment instead of uv's cache.
Rerun `mindroom service install` after upgrading MindRoom.
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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
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 service status and recent logs.
While the running service still waits for pairing, the status adds a pairing: required line, judged from the config and storage paths saved in the installed service.
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 kept 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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
check-active-responses
Check whether a restart would interrupt live work in the running MindRoom: Matrix responses, OpenAI-compatible requests, voice calls, and background script runs. Run it before restarting, upgrading, or reloading a configuration that restarts agents.
mindroom check-active-responses
mindroom check-active-responses --json
mindroom check-active-responses --details
mindroom check-active-responses --wait 1800
| Exit code | Meaning |
|---|---|
0 |
Runtime ready, admission open, and no active Matrix work, OpenAI requests, voice calls, or interruptible script runs. |
1 |
Matrix work, OpenAI-compatible requests, voice calls, or interruptible script runs are active. |
2 |
Status unavailable, including startup, replacement, connection failure, or an incompatible server. |
The snapshot reports these counts:
| Field | Counts |
|---|---|
active_matrix_operations |
Admitted Matrix work, including planning and waits for a response lock; nested work counts separately, so this is not a count of unique responses. |
active_openai_requests |
OpenAI-compatible chat completion requests until their response body finishes. |
active_calls |
Voice calls an agent has joined or is joining; a restart, or a reload that restarts the call agent, drops the agent from the call. |
interruptible_script_runs |
Unfinished background script runs that a restart would interrupt. |
recoverable_script_runs |
Script runs that survive a restart; they do not make the runtime busy, but treat them as busy before a change that interrupts them. |
Persisted approval waits, unadmitted queued messages, and unrelated background jobs are not counted.
The result is a point-in-time observation, not a restart lock, so new work can start right afterward.
The check needs the bundled API running inside mindroom run; with multiple processes, check each one.
--details adds one row per active response or call with channel (matrix, openai, or call), responder (the agent or team/<team-name>), and requester_id, plus script_runs rows with run_id, responder, requester_id, and recoverable.
Unknown identities are null in JSON and shown as unknown in text.
Detail rows need not match active_matrix_operations, because work can be busy before a response identity exists.
--details requires MINDROOM_API_KEY in the selected runtime environment, including when browser proxy authentication is enabled; a missing or rejected key exits 2.
Aggregate output never includes identities.
--wait SECONDS polls every 5 seconds while busy and exits as soon as the runtime is idle.
If work is still active at the deadline, it exits 1 with the last busy snapshot, and an unavailable result ends the wait immediately with exit 2.
Only the final snapshot is printed, and the total runtime can exceed --wait by up to one request timeout.
The CLI reads the unauthenticated GET /api/responses/activity endpoint, or GET /api/responses/activity/details with a bearer token for --details.
The URL comes from --url, then MINDROOM_URL from the selected environment, then http://127.0.0.1:8765.
--config selects the environment and --timeout sets each request's timeout (10 seconds by default).
MINDROOM_API_KEY is sent only over HTTPS or loopback HTTP, and redirects are not followed.
version
Show the installed MindRoom version.
Usage: root version [OPTIONS]
Show the current version of Mindroom.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
local-stack-setup
Start a local Synapse homeserver and the MindRoom Chat client container from the core MindRoom repository's local/matrix development Compose files.
By default it writes MATRIX_HOMESERVER and MATRIX_SERVER_NAME to the .env next to your active config.yaml, so mindroom run works without extra exports; --no-persist-env skips this.
For an https:// homeserver it also writes MATRIX_SSL_VERIFY=false, which turns off certificate checks for that homeserver only, so remove it before switching to hosted Matrix.
Usage: root local-stack-setup [OPTIONS]
Start local Synapse + MindRoom Chat using Docker only.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --synapse-dir PATH Directory │
│ containing Synapse │
│ docker-compose.yml │
│ (core MindRoom │
│ repo: │
│ local/matrix). │
│ [default: │
│ local/matrix] │
│ --homeserver-url TEXT Homeserver URL that │
│ MindRoom Chat 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 Chat │
│ container. │
│ [default: 8080] │
│ --cinny-image TEXT Docker image for │
│ MindRoom Chat. │
│ [default: │
│ ghcr.io/mindroom-a… │
│ --cinny-container-n… TEXT Container name for │
│ MindRoom Chat │
│ (legacy default │
│ retained for │
│ compatibility). │
│ [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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
plugins
Install, update, and validate external plugins with mindroom plugins install, mindroom plugins update, and mindroom plugins check.
See Installing plugins and Compatibility checks.
desktop
Connect explicitly allowlisted local applications, read-only folders, and locally approved shell commands to cloud MindRoom over Matrix end-to-end encryption. See the Matrix Desktop Bridge guide for setup, security, and every behavior these commands control.
Usage: root desktop [OPTIONS] COMMAND [ARGS]...
Connect allowlisted local apps, read-only folders, and locally approved shell commands
to cloud MindRoom over Matrix E2EE.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ app Run the native app's private structured helper over inherited standard I/O. │
│ login Log in once, create an Olm device, and save its access token privately. │
│ pair Claim one requester-agent pairing through authenticated Matrix E2EE. │
│ setup Pair and save the connection shared with the macOS app. │
│ access Save read-only folders and shell requests shared with the macOS app; omitted │
│ options keep saved values. │
│ run Run the bridge with the saved app, folder, and shell setup; flags override │
│ this run only. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
desktop setup
Log in when needed, claim the pairing from !desktop setup, and save the connection shared with the macOS app.
Use --allow-app to save app choices at the same time.
Usage: root desktop setup [OPTIONS]
Pair and save the connection shared with the macOS app.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ * --code TEXT Short-lived code returned by !desktop │
│ setup. │
│ [required] │
│ * --controller-user-id TEXT Pinned cloud controller Matrix user. │
│ [required] │
│ * --controller-device-id TEXT Pinned cloud controller device. │
│ [required] │
│ * --controller-ed25519 TEXT Pinned controller fingerprint. [required] │
│ --allow-agent TEXT Agent name from the setup message; │
│ prompts if omitted. Repeat as needed. │
│ --allow-app TEXT Save allowed app IDs, or choose apps │
│ later in the macOS app. │
│ --user-id TEXT Expected Matrix user ID; required for │
│ password login and optional for SSO. │
│ --homeserver TEXT Matrix homeserver URL; defaults to the │
│ configured MindRoom homeserver. │
│ --cloudflare-access Authenticate Matrix requests │
│ interactively with the local cloudflared │
│ CLI. │
│ [env var: │
│ MINDROOM_DESKTOP_CLOUDFLARE_ACCESS] │
│ --matrix-http-headers-file PATH Owner-only JSON file of HTTP headers │
│ added to every Matrix request. │
│ [env var: │
│ MINDROOM_DESKTOP_MATRIX_HTTP_HEADERS_FIL… │
│ --config -c PATH MindRoom config path used for runtime │
│ env. │
│ --storage-path -s PATH Desktop bridge state directory. │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
desktop access
Save read-only folders and shell command requests in the setup shared with the macOS app; omitted options keep the saved values. Shell commands run with your full account access; see Shell Commands before enabling them.
Usage: root desktop access [OPTIONS]
Save read-only folders and shell requests shared with the macOS app; omitted options
keep saved values.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --allow-folder PATH Add a folder agents may list and read, never │
│ write; repeat as needed. │
│ --clear-folders Remove every saved read-only folder. │
│ --shell --no-shell Let agents request shell commands, each │
│ approved on this computer while the bridge │
│ runs. │
│ --config -c PATH MindRoom config path used for runtime env. │
│ --storage-path -s PATH Desktop bridge state directory. │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
desktop login
Create and privately save the dedicated local desktop Matrix device.
Usage: root desktop login [OPTIONS]
Log in once, create an Olm device, and save its access token privately.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --user-id TEXT Expected Matrix │
│ user ID; required │
│ for password login │
│ and optional for │
│ SSO. │
│ --homeserver TEXT Matrix homeserver │
│ URL; defaults to │
│ the configured │
│ MindRoom │
│ homeserver. │
│ --login-method [auto|password|sso] Matrix login │
│ method. Auto uses │
│ browser SSO when │
│ advertised, │
│ otherwise password. │
│ [default: auto] │
│ --sso-idp TEXT Matrix SSO │
│ identity-provider │
│ ID. Selects SSO │
│ when login method │
│ is auto. │
│ --open-browser --no-open-browser Open Matrix SSO in │
│ the default │
│ browser; otherwise │
│ print the URL. │
│ [default: │
│ open-browser] │
│ --cloudflare-access Authenticate Matrix │
│ requests │
│ interactively with │
│ the local │
│ cloudflared CLI. │
│ [env var: │
│ MINDROOM_DESKTOP_C… │
│ --replace Replace the saved │
│ session with a │
│ fresh Matrix │
│ device. │
│ --matrix-http-head… PATH Owner-only JSON │
│ file of HTTP │
│ headers added to │
│ every Matrix │
│ request. │
│ [env var: │
│ MINDROOM_DESKTOP_M… │
│ --config -c PATH MindRoom config │
│ path used for │
│ runtime env. │
│ --storage-path -s PATH Desktop bridge │
│ state directory. │
│ --help -h Show this message │
│ and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
desktop run
Run the local bridge with the setup saved by the terminal or macOS app; flags override settings for this run only.
Applications stay observe-only unless --allow-control grants a short lease, and with shell requests enabled, each command waits for an answer at this terminal unless --shell-auto-approve-minutes is set.
Usage: root desktop run [OPTIONS]
Run the bridge with the saved app, folder, and shell setup; flags override this run only.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────╮
│ --controller-user-id TEXT Pinned cloud │
│ controller Matrix │
│ user. │
│ --controller-device-… TEXT Pinned cloud │
│ controller device. │
│ --controller-ed25519 TEXT Pinned controller │
│ fingerprint. │
│ --allow-requester TEXT Human Matrix │
│ requester allowed to │
│ operate this │
│ desktop; repeat as │
│ needed. │
│ --allow-agent TEXT MindRoom agent name │
│ allowed to operate │
│ this desktop; repeat │
│ as needed. │
│ --allow-app TEXT Exact local │
│ application ID │
│ exposed to the │
│ agent; repeat as │
│ needed. │
│ --allow-control Enable semantic and │
│ fallback app input │
│ for a short local │
│ lease. Default: apps │
│ are observe-only. │
│ --lease-minutes INTEGER RANGE Local control lease │
│ [1<=x<=60] duration. │
│ [default: 15] │
│ --shell-auto-approve… INTEGER RANGE Approve shell │
│ [1<=x<=60] commands from every │
│ allowed requester │
│ and agent │
│ automatically for │
│ this many minutes of │
│ this run; never │
│ saved. │
│ --max-screenshot-wid… INTEGER RANGE │
│ [320<=x<=3840] │
│ --jpeg-quality INTEGER RANGE │
│ [40<=x<=95] │
│ --browser-extension --no-browser-exten… Expose Playwright │
│ MCP control of an │
│ existing browser │
│ profile when its │
│ extension is │
│ installed. │
│ --browser-executable PATH Chrome-family │
│ executable to open │
│ the Playwright │
│ extension connection │
│ page, including │
│ Brave. │
│ --browser-user-data-… PATH Existing browser │
│ user-data root │
│ containing the │
│ profile where the │
│ extension is │
│ installed. │
│ --browser-timeout-se… INTEGER RANGE Local Playwright MCP │
│ [1<=x<=120] call timeout. │
│ --log-level -l TEXT [default: INFO] │
│ --cloudflare-access Authenticate Matrix │
│ requests │
│ interactively with │
│ the local │
│ cloudflared CLI. │
│ [env var: │
│ MINDROOM_DESKTOP_CL… │
│ --matrix-http-header… PATH Owner-only JSON file │
│ of HTTP headers │
│ added to every │
│ Matrix request. │
│ [env var: │
│ MINDROOM_DESKTOP_MA… │
│ --config -c PATH MindRoom config path │
│ used for runtime │
│ env. │
│ --storage-path -s PATH Desktop bridge state │
│ directory. │
│ --help -h Show this message │
│ and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────╯
avatars
Generate and sync managed avatars; see Managed Avatars for defaults, file locations, and overrides.
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 avatar files for entities that have none, using OpenAI with OPENAI_API_KEY or OPENAI_API_KEY_FILE.
Use --force to overwrite existing files 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
Apply configured room and root-Space avatars to Matrix using the router account.
Existing Matrix avatars are kept unless you pass --force.
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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
threads
Export Matrix threads to local YAML files.
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 through a running MindRoom instance to searchable YAML │
│ files. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
threads export
See threads export for requirements and output.
Usage: root threads export [OPTIONS]
Export Matrix threads through a running MindRoom instance to searchable YAML files.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --url TEXT Running MindRoom URL; defaults │
│ to MINDROOM_URL or │
│ localhost:8765. │
│ --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] │
│ --invited-rooms --no-invited-rooms Include rooms joined through │
│ authorized invites │
│ (user-created rooms). │
│ [default: invited-rooms] │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
mindroom threads export --storage-path mindroom_data --output "$HOME/mindroom-thread-exports"
mindroom threads export --storage-path mindroom_data --room lobby
mindroom threads export --storage-path mindroom_data --watch --interval 300
mindroom threads export --url http://127.0.0.1:9000 --storage-path mindroom_data
journal
Inspect and rebind the event journal; see Journal binding.
Usage: root journal [OPTIONS] COMMAND [ARGS]...
Inspect and rebind the durable event journal.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ adopt Bind this install to the configured event-journal database. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
journal adopt
See journal adopt before running it.
Usage: root journal adopt [OPTIONS]
Bind this install to the configured event-journal database.
MindRoom refuses to start against a journal it is not bound to, because
using a different one loses turn deduplication, delivery ownership, and
recovery ownership without any error. This is how you say the change was
deliberate.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --config -c PATH Use this config file path. │
│ --storage-path -s PATH Base directory for persistent MindRoom data. │
│ --yes -y Adopt without confirming, even when another journal is │
│ already bound. │
│ --force Adopt even though another process still has this │
│ install's journal open. │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
mindroom journal adopt --storage-path mindroom_data
mindroom journal adopt --storage-path mindroom_data --yes
debug-report
Collect everything the backend stored about one conversation into a single JSON document, for example to debug a chat bug report. The input is the JSON file a MindRoom Chat Report a bug message carries, or plain identifiers. See Bug Reports for how users send those reports and how administrators receive them.
The report includes the event journal's turn records, admitted events, and outbound deliveries, the conversation's Agno runs of agents, teams, private instances, and system usage, tracking/tool_calls.jsonl and its rotations, the LLM request logs, and the mindroom_*.log files.
Each source lists the files it read under paths and has a status of ok, missing (nothing to read there), or error with the message under error; a source that cannot be read, such as a locked or corrupt database, does not stop the others.
Successful tool calls and LLM requests are only logged when debug.log_llm_requests is enabled.
Nothing is redacted, and the newest matches are kept: up to 100 Agno runs, 1,000 records per JSONL source, and 2,000 log lines of 4,000 characters each, with dropped and truncated counting what was left out or shortened.
Run it on the MindRoom host with the same --config and --storage-path the service uses, and hand the bug report and the output to whoever debugs the issue.
When debug.llm_request_log_dir is relative, run the command from the service's working directory.
The command never writes the config and reads only its event_journal and debug.llm_request_log_dir settings, so a config the runtime would reject still locates the data; a PostgreSQL journal URL comes from event_journal.database_url, the config directory's .env, or the environment, and an unresolved URL reports the journal sources as errors.
--event alone does not reach Agno runs or outbound deliveries; pass --room and --thread, or a bug report file.
Usage: root debug-report [OPTIONS] [REPORT]
Collect everything the backend stored about a reported conversation, as JSON.
╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮
│ report [REPORT] MindRoom Chat bug report JSON, as attached to a Report a bug │
│ message. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --event -e TEXT Matrix event ID; repeatable. Conversation-wide sources │
│ (Agno sessions, deliveries) need --room/--thread, or a │
│ report file. │
│ --room -r TEXT Matrix room ID. │
│ --thread -t TEXT Thread root event ID. │
│ --config -c PATH Use this config file path. │
│ --storage-path -s PATH Base directory for persistent MindRoom data. │
│ --output -o PATH Write the JSON here instead of stdout. │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
mindroom debug-report bug-report.json --output backend-report.json
mindroom debug-report --room '!room:example.com' --thread '$thread_root' --config ~/.mindroom/config.yaml
trigger
Send signed external trigger requests from cron jobs and watcher scripts; see External Triggers.
Usage: root trigger [OPTIONS] COMMAND [ARGS]...
Send signed external triggers.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ keygen Generate an Ed25519 trigger signing key. │
│ send Send a signed external trigger request. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
trigger keygen
Generate an Ed25519 signing key pair for an external trigger.
Usage: root trigger keygen [OPTIONS]
Generate an Ed25519 trigger signing key.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --private-key-file PATH Path where the base64 raw Ed25519 private key should │
│ be written. │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
trigger send
Send one signed trigger request to MindRoom.
Usage: root trigger send [OPTIONS] TRIGGER_ID
Send a signed external trigger request.
╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮
│ * trigger_id TEXT Configured external trigger id. [required] │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ * --key-file FILE Base64 raw Ed25519 private key file. │
│ [required] │
│ * --kind TEXT Trigger payload kind. [required] │
│ * --message TEXT Trigger payload message. [required] │
│ --event-id TEXT Optional idempotency event id. │
│ --title TEXT Optional trigger title. │
│ --thread-key TEXT Optional key; deliveries sharing it │
│ land in one Matrix thread on new_thread │
│ triggers. │
│ --data-json TEXT Optional JSON object for trigger data. │
│ --timeout FLOAT HTTP request timeout in seconds. │
│ [default: 10.0] │
│ --verify-tls --no-verify-tls Verify TLS certificates. │
│ [default: verify-tls] │
│ --url TEXT MindRoom base URL. │
│ [env var: MINDROOM_URL] │
│ [default: http://127.0.0.1:8765] │
│ --key-id TEXT Trigger signing key id. │
│ [default: default] │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯