Skip to content

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

mindroom run --log-level DEBUG

--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: run codex login first; see Codex Models for the generated models.
  • kimi: run kimi and /login first; see Kimi Models.
  • ollama: generates gemma4 as default and qwen3.8:27b as qwen3_8_27b, each loaded with a 32,768-token context (see Ollama Context Size to change it), with OLLAMA_HOST=http://localhost:11434; pull both models first with ollama pull gemma4 and ollama pull qwen3.8:27b.
  • llama.cpp: generates Unsloth GGUF models for a llama.cpp server at http://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.

mindroom config resolve --path ./config.yaml

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 validate fails 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 validate does. 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 as base_url or default_headers) or its provider's endpoint variable (such as OPENAI_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, because mindroom run pairs 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.

mindroom connect --open-browser

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.

mindroom local-stack-setup --synapse-dir /path/to/mindroom/local/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]             │
╰────────────────────────────────────────────────────────────────────────────────────────╯