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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Get started ──────────────────────────────────────────────────────────────────────────╮
│ run Set up on first run, pair, and start MindRoom. │
│ connect Pair this machine with your MindRoom Chat account. │
│ doctor Check your setup for common problems. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Configure ────────────────────────────────────────────────────────────────────────────╮
│ config Create, edit, and validate config.yaml. │
│ plugins Check, install, and update MindRoom plugins. │
│ avatars Generate and sync agent, room, and space avatars. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Keep running ─────────────────────────────────────────────────────────────────────────╮
│ service Run MindRoom in the background, starting at login. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Desktop ──────────────────────────────────────────────────────────────────────────────╮
│ desktop Share local apps, folders, and shell commands with cloud │
│ MindRoom. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Troubleshoot ─────────────────────────────────────────────────────────────────────────╮
│ debug-report Collect what MindRoom stored about a reported conversation, │
│ as JSON. │
│ version Show the MindRoom version. │
│ threads Export Matrix threads to searchable files. │
│ journal Inspect and rebind the durable event journal. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Automation ───────────────────────────────────────────────────────────────────────────╮
│ check-active-responses Check whether MindRoom has live work. │
│ trigger Send signed external triggers. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Development ──────────────────────────────────────────────────────────────────────────╮
│ local-stack-setup Start local Synapse + MindRoom Chat using Docker only. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
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]
Set up on first run, pair, and start MindRoom.
When no config exists, MindRoom creates a starter config for MindRoom Chat, asking for
the model provider in a terminal or taking it from --provider.
An install on MindRoom Chat that is not paired yet pairs this machine with your account,
and a first run in a terminal offers to keep running in the background at login (see
--service).
MindRoom then creates the agent accounts and rooms from config.yaml, keeps room
memberships in sync, and starts the dashboard and API (disable with --no-api).
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --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. │
│ --log-level -l TEXT Set the logging level (DEBUG, INFO, WARNING, │
│ ERROR) │
│ [env var: LOG_LEVEL] │
│ [default: INFO] │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Paths ────────────────────────────────────────────────────────────────────────────────╮
│ --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) │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Dashboard ────────────────────────────────────────────────────────────────────────────╮
│ --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] │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Deployment ───────────────────────────────────────────────────────────────────────────╮
│ --bootstrap-config-bundle PATH Initialize the selected config │
│ directory from this bundle only when │
│ the directory is absent. │
│ --bootstrap-config-bundle-revision TEXT Install a changed bootstrap revision │
│ through native validation; preserve a │
│ matching active revision. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
Examples
mindroom run Set up on first run, pair, and start
mindroom run --provider anthropic Skip the provider question on first run
mindroom run --service Run in the background at login
mindroom run --no-api Start without the dashboard
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,httpx2: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]...
Create, edit, and validate config.yaml.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Create and edit ──────────────────────────────────────────────────────────────────────╮
│ init Create a starter config.yaml with a personal agent and model. │
│ edit Open config.yaml in your default editor. │
│ use-local-model Make a local model the default, keeping agents' explicit model │
│ choices. │
│ migrate Migrate config.yaml to membership access settings. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Inspect ──────────────────────────────────────────────────────────────────────────────╮
│ show Display the current config file with syntax highlighting. │
│ 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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Deployment ───────────────────────────────────────────────────────────────────────────╮
│ fingerprint Print the SHA-256 of the config and every file it includes. │
│ install-bundle Validate and install a complete config tree. │
│ classify-change Classify the differences between two config trees. │
│ apply-bundle Hot-apply a config tree change limited to YAML or include sources. │
│ check-applied Confirm that the runtime applied a config. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
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, each loaded with a 32,768-token context (see Ollama Context Size to change it), 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.
It also loads the configured plugins and fails on automation names no loaded plugin provides or that two register.
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, matches the config schema, and lists only automations a loaded plugin provides, the same checks
config validatefails on. - Providers: API keys for each configured provider (Anthropic, OpenAI, Ollama, Vertex AI Claude, and others) are valid.
Doctor also warns about each environment variable a model needs but nothing sets, such as a missing key, Bedrock region, or Azure endpoint, as
config validatedoes. Doctor checks the key the runtime uses, whether it comes from the environment or was saved in the dashboard, and names its source (see Credentials from the Environment). Doctor skips the key check and reports it as not checked for a model that uses a custom endpoint, meaning its config sets an endpoint or headers (such asbase_urlordefault_headers) or its provider's endpoint variable (such asOPENAI_BASE_URL) is set. - 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: each bot's persisted Matrix device still has its local encryption store.
Usage: root doctor [OPTIONS]
Check your setup for common problems.
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]...
Run MindRoom in the background, starting at login.
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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
Examples
mindroom service install Install and start the service
mindroom service status Check that it runs and show recent logs
mindroom service restart Pick up changes to .env
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.
A request that times out is retried until the deadline and exits 2 only if the last request also times out.
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 MindRoom version.
╭─ 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]...
Share local apps, folders, and shell commands with cloud MindRoom.
Agents reach only allowlisted apps, read-only folders, and shell commands approved here,
over Matrix E2EE.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Set up and run ───────────────────────────────────────────────────────────────────────╮
│ setup Pair and save the connection shared with the macOS app. │
│ access Save the read-only folders and shell access shared with the macOS app. │
│ run Run the bridge with the saved app, folder, and shell setup. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Advanced ─────────────────────────────────────────────────────────────────────────────╮
│ app Serve the macOS app's private helper over standard input and output. │
│ login Log in once, create an Olm device, and save its access token privately. │
│ pair Claim one requester-agent pairing through authenticated Matrix E2EE. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
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 ──────────────────────────────────────────────────────────────────────────────╮
│ --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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Pairing ──────────────────────────────────────────────────────────────────────────────╮
│ * --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] │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Access ───────────────────────────────────────────────────────────────────────────────╮
│ --allow-requester TEXT Chat user from the setup message; defaults to the │
│ logged-in account. Repeat as needed. │
│ --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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Matrix connection ────────────────────────────────────────────────────────────────────╮
│ --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_FILE] │
╰────────────────────────────────────────────────────────────────────────────────────────╯
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 the read-only folders and shell access shared with the macOS app.
Options you leave out keep their 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 ──────────────────────────────────────────────────────────────────────────────╮
│ --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] │
│ --replace Replace the saved │
│ session with a fresh │
│ Matrix device. │
│ --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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Matrix connection ────────────────────────────────────────────────────────────────────╮
│ --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_FILE] │
╰────────────────────────────────────────────────────────────────────────────────────────╯
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 the saved setup for this run only.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────╮
│ --log-level -l TEXT Set the logging level (DEBUG, INFO, WARNING, ERROR) │
│ [default: INFO] │
│ --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. │
╰──────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Access ─────────────────────────────────────────────────────────────────────────────────────╮
│ --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 [1<=x<=60] Local control lease duration. │
│ [default: 15] │
│ --shell-auto-approve-minutes INTEGER RANGE [1<=x<=60] Approve shell commands from │
│ every allowed requester and │
│ agent automatically for this │
│ many minutes of this run; │
│ never saved. │
╰──────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Screenshots ────────────────────────────────────────────────────────────────────────────────╮
│ --max-screenshot-width INTEGER RANGE [320<=x<=3840] Widest screenshot sent to │
│ agents, in pixels; defaults to │
│ the saved setup (1568 unless │
│ changed). │
│ --jpeg-quality INTEGER RANGE [40<=x<=95] JPEG quality of screenshots sent │
│ to agents; defaults to the saved │
│ setup (80 unless changed). │
╰──────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Browser ────────────────────────────────────────────────────────────────────────────────────╮
│ --browser-extension --no-browser-extension Expose Playwright MCP control of an │
│ existing browser profile when its │
│ extension is installed. │
╰──────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Browser extension ──────────────────────────────────────────────────────────────────────────╮
│ --browser-executable PATH Chrome-family executable to open │
│ the Playwright extension │
│ connection page, including │
│ Brave. │
│ --browser-user-data-dir PATH Existing browser user-data root │
│ containing the profile where the │
│ extension is installed. │
│ --browser-timeout-seconds INTEGER RANGE [1<=x<=120] Local Playwright MCP call │
│ timeout. │
╰──────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Controller ─────────────────────────────────────────────────────────────────────────────────╮
│ --controller-user-id TEXT Pinned cloud controller Matrix user. │
│ --controller-device-id TEXT Pinned cloud controller device. │
│ --controller-ed25519 TEXT Pinned controller fingerprint. │
╰──────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Matrix connection ──────────────────────────────────────────────────────────────────────────╮
│ --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_FILE] │
╰──────────────────────────────────────────────────────────────────────────────────────────────╯
avatars
Generate and sync managed avatars; see Managed Avatars for defaults, file locations, and overrides.
Usage: root avatars [OPTIONS] COMMAND [ARGS]...
Generate and sync agent, room, and space avatars.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ generate Generate missing managed avatar files in the workspace. │
│ sync Sync room and root-space avatars to Matrix. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
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 room and root-space avatars to Matrix.
Uses the router account that `mindroom run` initialized.
╭─ 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 searchable files.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ export Export Matrix threads from a running MindRoom to searchable YAML files. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
threads export
See threads export for requirements and output.
Usage: root threads export [OPTIONS]
Export Matrix threads from a running MindRoom 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. │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Filter ───────────────────────────────────────────────────────────────────────────────╮
│ --room -r TEXT Filter exported rooms by a │
│ substring of the room key, │
│ alias, name, or Matrix room ID. │
│ --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] │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Watch ────────────────────────────────────────────────────────────────────────────────╮
│ --watch Repeat the export forever on a fixed interval. │
│ --interval INTEGER Watch interval in seconds. [default: 300] │
╰────────────────────────────────────────────────────────────────────────────────────────╯
Examples
mindroom threads export Export every room once
mindroom threads export --room lobby Only rooms matching lobby
mindroom threads export --watch --interval 600 Export again every 10 minutes
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, message deletions, admitted events, and outbound deliveries, the conversation's stored 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 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 stored runs or outbound deliveries; pass --room and --thread, or a bug report file.
Usage: root debug-report [OPTIONS] [REPORT]
Collect what MindRoom 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 │
│ (stored runs, 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] │
│ --key-id TEXT Trigger signing key id. [default: default] │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Payload ──────────────────────────────────────────────────────────────────────────────╮
│ * --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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Connection ───────────────────────────────────────────────────────────────────────────╮
│ --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] │
╰────────────────────────────────────────────────────────────────────────────────────────╯