CLI Reference
MindRoom provides a command-line interface for managing agents.
Basic Usage
Commands
Usage: root [OPTIONS] COMMAND [ARGS]...
AI agents that live in Matrix and work everywhere via bridges.
Quick start:
mindroom config init Create a starter config
mindroom run Start the system
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy it or │
│ customize the installation. │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ check-active-responses Check live responses; exit 0 idle, 1 busy, or 2 unavailable. │
│ version Show the current version of Mindroom. │
│ run Run the mindroom multi-agent system. │
│ doctor Check your environment for common issues. │
│ connect Pair this local MindRoom install with the hosted provisioning │
│ service. │
│ local-stack-setup Start local Synapse + MindRoom Chat using Docker only. │
│ config Manage MindRoom configuration files. │
│ plugins Validate and vendor external MindRoom plugins. │
│ desktop Connect allowlisted local applications to cloud MindRoom over │
│ Matrix E2EE. │
│ avatars Generate and sync managed avatar assets. │
│ threads Export Matrix threads to local files. │
│ journal Inspect and rebind the durable event journal. │
│ service Install and manage MindRoom as a background user service. │
│ trigger Send signed external triggers. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
check-active-responses
Check the running process's admitted Matrix work and OpenAI-compatible requests.
mindroom check-active-responses
mindroom check-active-responses --json
mindroom check-active-responses --details
mindroom check-active-responses --details --json
| Exit code | Meaning |
|---|---|
0 |
Runtime ready, admission open, and no admitted Matrix work or active OpenAI requests. |
1 |
Admitted Matrix work or OpenAI-compatible requests are active. |
2 |
Status unavailable, including startup, replacement, connection failure, or an incompatible server. |
The command reads GET /api/responses/activity, an unauthenticated operational probe exposing only runtime phase, admission state, and counts.
The bundled API must be enabled and connected to the orchestrator; an API-only process cannot report the runtime as idle.
Responses carry Cache-Control: no-store.
--details uses GET /api/responses/activity/details and adds one row per response observed at the central Matrix response lifecycle or OpenAI request entry point.
Rows contain channel, responder, and requester_id.
The responder is the configured agent or team/<team-name>; the requester comes from the canonical response envelope or authenticated OpenAI requester context.
Unknown identities are null in JSON and labeled unknown in text.
Identities are held only in memory; no database, history, or Matrix lookups are added.
Detailed access requires a configured MINDROOM_API_KEY and the matching bearer token, including when browser proxy authentication is enabled.
The CLI reads that key from the selected runtime environment.
The endpoint returns 503 if no key is configured and 401 for a missing or invalid token; the CLI exits 2 for either failure.
Aggregate output never includes identities.
active_matrix_operations reads the existing admission count, including planning and response lock waits.
Nested admission slots count separately, so this is not a count of unique responses.
Detailed rows describe response lifecycles and do not need to match that count; planning and other admitted work can be busy before a response identity is available.
active_openai_requests counts chat completion HTTP requests through their normal response-body lifetime.
Persisted approval waits, delivery recovery outside admission, cleanup that outlives its response, unadmitted queues, and unrelated background jobs are outside this snapshot.
This is a point-in-time observation, not a drain or restart lock. New work can start immediately afterward. For multiple processes, check each process directly.
The URL defaults to MINDROOM_URL from the selected environment, then http://127.0.0.1:8765.
Use --config /path/to/config.yaml to select the environment, --url to override the server, and --timeout to bound the request (10 seconds by default).
The CLI sends MINDROOM_API_KEY when configured; credentialed remote requests require HTTPS, while loopback HTTP is supported.
Redirects are disabled.
version
Show the current MindRoom version.
Usage: root version [OPTIONS]
Show the current version of Mindroom.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
run
Start MindRoom with your configuration.
Usage: root run [OPTIONS]
Run the mindroom multi-agent system.
This command starts the multi-agent bot system which automatically:
- Creates all necessary user and agent accounts
- Creates all rooms defined in config.yaml
- Manages agent room memberships
- Starts the bundled dashboard/API server (disable with --no-api)
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --log-level -l TEXT Set the logging level (DEBUG, INFO, WARNING, │
│ ERROR) │
│ [env var: LOG_LEVEL] │
│ [default: INFO] │
│ --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) │
│ --api --no-api Start the bundled dashboard/API server │
│ alongside the bot │
│ [default: api] │
│ --api-port INTEGER Port for the bundled dashboard/API server │
│ [default: 8765] │
│ --api-host TEXT Host for the bundled dashboard/API server │
│ [default: 0.0.0.0] │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
desktop
Connect explicitly allowlisted local applications to cloud MindRoom over Matrix end-to-end encryption. See the Matrix Desktop Bridge guide for the complete secure setup.
Usage: root desktop [OPTIONS] COMMAND [ARGS]...
Connect allowlisted local applications to cloud MindRoom over Matrix E2EE.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ app Run the native app's private structured helper over inherited standard I/O. │
│ login Log in once, create an Olm device, and save its access token privately. │
│ pair Claim one requester-agent pairing through authenticated Matrix E2EE. │
│ setup Log in when needed, then claim one requester-agent pairing. │
│ run Run the outbound-only Matrix sync loop and execute locally authorized │
│ commands. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
desktop setup
Log in when no saved local Desktop session exists, then claim the requester-agent pairing in one command.
Usage: root desktop setup [OPTIONS]
Log in when needed, then claim one requester-agent pairing.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ * --code TEXT Short-lived code returned by !desktop │
│ setup. │
│ [required] │
│ * --controller-user-id TEXT Pinned cloud controller Matrix user. │
│ [required] │
│ * --controller-device-id TEXT Pinned cloud controller device. │
│ [required] │
│ * --controller-ed25519 TEXT Pinned controller fingerprint. [required] │
│ --user-id TEXT Expected Matrix user ID; required for │
│ password login and optional for SSO. │
│ --homeserver TEXT Matrix homeserver URL; defaults to the │
│ configured MindRoom homeserver. │
│ --cloudflare-access Authenticate Matrix requests │
│ interactively with the local cloudflared │
│ CLI. │
│ [env var: │
│ MINDROOM_DESKTOP_CLOUDFLARE_ACCESS] │
│ --matrix-http-headers-file PATH Owner-only JSON file of HTTP headers │
│ added to every Matrix request. │
│ [env var: │
│ MINDROOM_DESKTOP_MATRIX_HTTP_HEADERS_FIL… │
│ --config -c PATH MindRoom config path used for runtime │
│ env. │
│ --storage-path -s PATH Desktop bridge state directory. │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
desktop login
Create and privately save the dedicated local desktop Matrix device.
Usage: root desktop login [OPTIONS]
Log in once, create an Olm device, and save its access token privately.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --user-id TEXT Expected Matrix │
│ user ID; required │
│ for password login │
│ and optional for │
│ SSO. │
│ --homeserver TEXT Matrix homeserver │
│ URL; defaults to │
│ the configured │
│ MindRoom │
│ homeserver. │
│ --login-method [auto|password|sso] Matrix login │
│ method. Auto uses │
│ password when │
│ advertised, │
│ otherwise browser │
│ SSO. │
│ [default: auto] │
│ --sso-idp TEXT Matrix SSO │
│ identity-provider │
│ ID. Selects SSO │
│ when login method │
│ is auto. │
│ --open-browser --no-open-browser Open Matrix SSO in │
│ the default │
│ browser; otherwise │
│ print the URL. │
│ [default: │
│ open-browser] │
│ --cloudflare-access Authenticate Matrix │
│ requests │
│ interactively with │
│ the local │
│ cloudflared CLI. │
│ [env var: │
│ MINDROOM_DESKTOP_C… │
│ --replace Replace the saved │
│ session with a │
│ fresh Matrix │
│ device. │
│ --matrix-http-head… PATH Owner-only JSON │
│ file of HTTP │
│ headers added to │
│ every Matrix │
│ request. │
│ [env var: │
│ MINDROOM_DESKTOP_M… │
│ --config -c PATH MindRoom config │
│ path used for │
│ runtime env. │
│ --storage-path -s PATH Desktop bridge │
│ state directory. │
│ --help -h Show this message │
│ and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
desktop run
Run the outbound-only local Matrix worker with exact controller, requester, and agent allowlists. Control remains disabled unless the local command grants a short lease.
Usage: root desktop run [OPTIONS]
Run the outbound-only Matrix sync loop and execute locally authorized commands.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────╮
│ * --controller-user-id TEXT Pinned cloud controller │
│ Matrix user. │
│ [required] │
│ * --controller-device-id TEXT Pinned cloud controller │
│ device. │
│ [required] │
│ * --controller-ed25519 TEXT Pinned controller │
│ fingerprint. │
│ [required] │
│ * --allow-requester TEXT Human Matrix requester │
│ allowed to operate this │
│ desktop; repeat as needed. │
│ [required] │
│ * --allow-agent TEXT MindRoom agent name │
│ allowed to operate this │
│ desktop; repeat as needed. │
│ [required] │
│ * --allow-app TEXT Exact local application ID │
│ exposed to the agent; │
│ repeat as needed. │
│ [required] │
│ --allow-control Enable semantic and │
│ fallback input for a short │
│ local lease. Default is │
│ observe-only. │
│ --lease-minutes INTEGER RANGE [1<=x<=60] Local control lease │
│ duration. │
│ [default: 15] │
│ --max-screenshot-width INTEGER RANGE [default: 1600] │
│ [320<=x<=3840] │
│ --jpeg-quality INTEGER RANGE [40<=x<=95] [default: 80] │
│ --browser-extension Expose Playwright MCP │
│ control of an existing │
│ browser profile when its │
│ extension is installed. │
│ --browser-executable PATH Chrome-family executable │
│ to open the Playwright │
│ extension connection page, │
│ including Brave. │
│ --browser-user-data-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. │
│ [default: 90] │
│ --log-level -l TEXT [default: INFO] │
│ --cloudflare-access Authenticate Matrix │
│ requests interactively │
│ with the local cloudflared │
│ CLI. │
│ [env var: │
│ MINDROOM_DESKTOP_CLOUDFLA… │
│ --matrix-http-headers-fi… PATH Owner-only JSON file of │
│ HTTP headers added to │
│ every Matrix request. │
│ [env var: │
│ MINDROOM_DESKTOP_MATRIX_H… │
│ --config -c PATH MindRoom config path used │
│ for runtime env. │
│ --storage-path -s PATH Desktop bridge state │
│ directory. │
│ --help -h Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────╯
avatars
Generate and sync managed avatar assets.
Usage: root avatars [OPTIONS] COMMAND [ARGS]...
Generate and sync managed avatar assets.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ generate Generate missing managed avatar files in the workspace. │
│ sync Sync configured room and root-space avatars to Matrix using the initialized │
│ router account. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
avatars generate
Generate missing managed avatar files in the workspace.
In a source checkout, generated files are written under ./avatars/.
In containerized deployments, generated overrides are written under the persistent MindRoom storage path.
Existing managed files are skipped by default.
Use --force to overwrite them after changing avatar prompts or styles.
Generation uses gpt-6-astra for prompt creation and gpt-image-2.5-sunburst for PNG rendering.
Both stages use OPENAI_API_KEY or the file-based OPENAI_API_KEY_FILE credential.
Usage: root avatars generate [OPTIONS]
Generate missing managed avatar files in the workspace.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --force Overwrite existing managed workspace avatar files. │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
avatars sync
Sync configured room and root-space avatars to Matrix using the initialized router account.
Existing Matrix avatars are skipped by default.
Use --force to replace them.
Usage: root avatars sync [OPTIONS]
Sync configured room and root-space avatars to Matrix using the initialized router
account.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --force Replace existing Matrix room and root-space avatars. │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
threads
Export Matrix threads to local files.
Usage: root threads [OPTIONS] COMMAND [ARGS]...
Export Matrix threads to local files.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ export Export Matrix threads through a running MindRoom instance to searchable YAML │
│ files. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
threads export
Export Matrix threads to YAML files for grep/ripgrep search.
Keep MindRoom running with its API enabled while exporting; both one-shot and --watch exports use its live Matrix clients and journal readers.
The CLI calls --url, then MINDROOM_URL from the selected runtime environment, or http://127.0.0.1:8765 by default.
Set MINDROOM_API_KEY when API authentication is enabled; hosted deployments require an authorized bearer token.
The selected --config and --storage-path must match the running installation, and output paths refer to that runtime's filesystem.
There is no offline export mode or separate Matrix login.
Rooms joined through authorized invites (user-created rooms) are exported too, each with the invited entity's own account, unless --no-invited-rooms is passed.
By default it writes to <storage>/thread_exports.
For a continuously updated copy inside an agent's own workspace, set thread_exports on the agent instead; see Thread Exports.
A thread file is only rewritten when its content changed, so exported_at reflects the last content-changing export.
Each thread document includes the latest MindRoom thread summary as thread.summary when one exists.
Each room directory also gets an index.json mapping every thread file to its message count, participants, latest summary, and last activity, sorted by most recent activity.
Complete passes normally remove exported room and thread files that are no longer present or authorized; a --room pass only reconciles the selected room.
The zero-room guard skips only final directory-wide reconciliation of rooms absent from the pass, while definitive per-room category or membership revocations still delete their exports.
A warning is logged when that guard preserves existing target state because the pass has no positive room evidence.
A complete room enumeration that returns zero threads preserves existing YAML exports for that room and logs a warning because an anomalous empty response cannot be distinguished from deletion of the final thread.
After either warning, verify the source state and remove the preserved export manually only when the deletion is confirmed; workspace git history remains the recovery path for mistaken cleanup.
Enabled targets whose resolved output directories are equal or nested are all skipped before Matrix work.
MindRoom claims an empty output root by writing a .mindroom-thread-exports ownership marker.
Any populated markerless root is refused and left unchanged, regardless of whether its contents resemble thread exports.
To use an existing populated root, create .mindroom-thread-exports inside it containing exactly {"format":"mindroom-thread-exports","version":1} followed by a newline.
Unrelated entries in a marked root, such as .DS_Store, a .git directory, or your own notes, are never deleted.
A refused root is skipped for the entire pass, so it is neither exported to nor cleaned up, and the skip is reported as a target failure.
Cleanup then removes only recognizable room directories and thread YAML files, leaving unrelated entries untouched and logged.
Retracting a room whose directory still holds unrelated entries removes only the exported files and leaves the directory in place, and repeating the pass stays a quiet no-op.
Output paths with a terminal ., .., or empty leaf are rejected, as are symlinked final output and room directories.
Thread bodies come from the journal projection, read as the same principal a running bot writes it under, so an exported thread reduces edits, redactions, and long-text sidecars exactly the way agent prompts do.
A thread nobody has read yet is built from the homeserver once and then costs no Matrix history call at all, so a repeated export pass is a local read.
Hydration writes through the runtime's existing journal owner; export does not open another journal or crypto store.
Normal config reloads wait for manual exports; forced replacement and shutdown cancel them and drain their history reads before closing their Matrix clients.
Every runtime replacement also cancels and drains automatic workspace exports, then queues a full pass that waits for publication to finish before borrowing current clients.
Automatic exports resume when replacement admission reopens, including after a failed or cancelled publication.
An interrupted pass preserves completed files; rerun the export to finish the pass and rebuild indexes.
Usage: root threads export [OPTIONS]
Export Matrix threads through a running MindRoom instance to searchable YAML files.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --url TEXT Running MindRoom URL; defaults │
│ to MINDROOM_URL or │
│ localhost:8765. │
│ --config -c PATH Use this config file path. │
│ --storage-path -s PATH Base directory for persistent │
│ MindRoom data. │
│ --output -o PATH Output directory. Defaults to │
│ <storage>/thread_exports. │
│ --room -r TEXT Filter exported rooms by a │
│ substring of the room key, │
│ alias, name, or Matrix room ID. │
│ --watch Repeat the export forever on a │
│ fixed interval. │
│ --interval INTEGER Watch interval in seconds. │
│ [default: 300] │
│ --max-thread-roots INTEGER Maximum thread roots to │
│ enumerate per room. │
│ [default: 2000] │
│ --invited-rooms --no-invited-rooms Include rooms joined through │
│ authorized invites │
│ (user-created rooms). │
│ [default: invited-rooms] │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
mindroom threads export --storage-path mindroom_data --output "$HOME/mindroom-thread-exports"
mindroom threads export --storage-path mindroom_data --room lobby
mindroom threads export --storage-path mindroom_data --watch --interval 300
mindroom threads export --url http://127.0.0.1:9000 --storage-path mindroom_data
journal
Inspect and rebind the durable event journal.
The event journal is the database that holds turn deduplication, delivery ownership, and recovery ownership. Every install is bound to exactly one, and MindRoom refuses to start against any other one, because using a stranger's journal does not fail — it answers every question confidently and about somebody else's history.
An install is bound the first time it opens a journal.
The database mints a generation when it is first used and never rewrites it, so the generation names the database rather than the process, and the binding recorded in <storage>/tracking/event_journal_binding.json names that generation.
A later start reads the configured database's generation before it opens the store and refuses when the two do not match.
Refusal happens before anything is created, so a database that gets refused is left exactly as it was found.
Each refusal is a different problem and says so:
| Message | What happened | What to do |
|---|---|---|
has never been used by this install |
The configured database carries no generation at all. | Usually a connection pointing somewhere new. Point event_journal back, or adopt deliberately. |
is a different journal from the one this install is bound to |
The configured database carries someone else's generation. | Usually a connection pointing at another install. Point event_journal back, or adopt deliberately. |
could not be read |
The binding file itself is corrupt or truncated. | Repair or delete <storage>/tracking/event_journal_binding.json, then adopt. |
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
Bind this install to the event-journal database that is configured right now.
This is the deliberate override of the startup refusal, and the only repair for an install whose binding has been lost.
Adopting gives up the deduplication, delivery, and recovery history held in the previously bound journal, so it asks for confirmation unless --yes is passed.
Stop MindRoom before adopting.
A running MindRoom keeps writing to the database it opened at startup, so adopting under it does not move the running install — it splits the install's history across two databases, and nothing will ever read the older one again.
A process that has the journal open holds an advisory claim on <storage>/tracking/event_journal_store.lock for as long as it has it open, and adoption refuses while that claim is held.
The claim ends when the store is closed, and the operating system withdraws it if the process dies, so a crashed MindRoom leaves nothing to clean up.
--force adopts anyway, for the case where the claim cannot be trusted: it is advisory, and it does not travel between hosts sharing one storage root over a network filesystem.
Adoption keeps the old binding until the new one is ready. If the candidate cannot be opened — an unreachable server, a bad DSN, a full disk — the command fails with the previous binding still in place, and the install starts exactly as it did before.
Moving a journal safely
Copying a database the supported way carries its generation with it, so a copy is accepted by the same binding and needs no adoption. That cuts both ways: a stale clone taken weeks ago carries the same generation as the live database and will be accepted without complaint, even though every turn since the clone was taken is missing from it. The generation proves the database is the same lineage, not that it is up to date, and nothing else checks.
For a quiesced migration:
- Stop MindRoom, and any
mindroom threads export --watchrunning against the same storage root. - Copy or dump-and-restore the database in full.
- Point
event_journalat the new location. - Start MindRoom. No adoption is needed, because the generation travelled with the data.
Adopt instead of copying only when you accept beginning the journal's history fresh.
Recovering from a failure
An install refuses to start and you did not move anything.
Check event_journal and the environment variable named by event_journal.database_url_env before adopting: a DSN that has drifted to a fresh database is the common cause, and adopting would throw the real journal's history away rather than find it.
An install refuses to start with could not be read.
The binding file is corrupt. Delete it and run mindroom journal adopt against the database you actually want; there is nothing recoverable inside it that the database does not already know.
Adoption refuses because the journal is in use.
Stop MindRoom and try again. Use --force only when you are certain nothing is running, for example after a host has been rebooted with a stale storage root on a network filesystem.
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
service
Install and manage MindRoom as a background user service.
MindRoom runs the version installed by this command through uv tool run and starts automatically at login.
Rerun mindroom service install after upgrading MindRoom.
On macOS, MindRoom uses launchd user agents.
On Linux, MindRoom uses systemd user services.
Usage: root service [OPTIONS] COMMAND [ARGS]...
Install and manage MindRoom as a background user service.
MindRoom runs the version installed by this command through `uv tool run` and starts
automatically at login.
Rerun `mindroom service install` after upgrading MindRoom.
Supported platforms:
- macOS: launchd (`~/Library/LaunchAgents/`)
- Linux: systemd user services (`~/.config/systemd/user/`)
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ install Install and start MindRoom as a background user service. │
│ uninstall Stop and remove the MindRoom user service. │
│ start Start the installed MindRoom user service. │
│ stop Stop the installed MindRoom user service without removing it. │
│ restart Restart the installed MindRoom user service. │
│ status Show MindRoom service status and recent logs. │
│ logs Follow MindRoom service logs. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
service install
Install and start MindRoom as a background user service.
Use --no-confirm for non-interactive setup.
Usage: root service install [OPTIONS]
Install and start MindRoom as a background user service.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --skip-deps Skip uv dependency check. │
│ --no-confirm -y Skip confirmation prompts. │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
service status
Show MindRoom service status and recent logs.
Usage: root service status [OPTIONS]
Show MindRoom service status and recent logs.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --logs -l INTEGER Number of recent log lines to show. Use 0 to hide logs. │
│ [default: 10] │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
service uninstall
Stop and remove the MindRoom user service.
On macOS, log files are preserved under ~/Library/Logs/mindroom/.
Usage: root service uninstall [OPTIONS]
Stop and remove the MindRoom user service.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --no-confirm -y Skip confirmation prompts. │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
doctor
Check your environment for common issues before running mindroom run.
Runs a series of checks in one pass:
- Config file exists and is valid YAML with correct Pydantic schema
- Providers — validates API keys for each configured provider (Anthropic, OpenAI, Ollama, Vertex AI Claude, etc.)
- Memory config — checks memory LLM and embedder reachability (Ollama, OpenAI embeddings, sentence-transformers)
- Matrix homeserver — verifies the homeserver is reachable via
/_matrix/client/versions - Storage — confirms the storage directory is writable
- Encryption stores — checks that persisted Matrix device identities still have their local E2EE stores
Usage: root doctor [OPTIONS]
Check your environment for common issues.
Runs connectivity, configuration, and credential checks in a single pass
so you can fix everything before running `mindroom run`.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --config -c PATH Use this config file path. Defaults the storage location │
│ to the selected config directory unless --storage-path │
│ is set. │
│ --storage-path -s PATH Base directory for persistent MindRoom data (state, │
│ sessions, tracking) │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
config
mindroom config migrate applies the membership access migration and preserves retired starter-memory settings.
Manage MindRoom configuration files.
The config subgroup contains commands for creating, viewing, editing, and validating your config.yaml.
Usage: root config [OPTIONS] COMMAND [ARGS]...
Manage MindRoom configuration files.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ init Create a starter config.yaml with a personal agent and model. │
│ show Display the current config file with syntax highlighting. │
│ edit Open config.yaml in your default editor. │
│ validate Validate config.yaml and check for common issues. │
│ resolve Print the fully merged config YAML with all !include tags resolved. │
│ path Show the resolved config file path and search locations. │
│ migrate Migrate config.yaml to membership access settings. │
│ fingerprint Print the config source SHA-256, including all transitively included │
│ files. │
│ check-applied Confirm config application; exit 0 applied, 1 pending/mismatch, 2 │
│ failed/restart-required/unavailable. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
config init
Create a starter config.yaml with the personal Mind agent, one model, file-based memory, and sensible defaults.
Matrix server presets (--matrix-server) choose where MindRoom should create Matrix users and rooms: mindroom.chat (default hosted Matrix) or self-hosted (your own homeserver).
Provider presets (--provider) set the default model: anthropic, azure, bedrock_claude, codex, kimi, llama.cpp, ollama, openai, openrouter, or vertexai_claude.
Generated configs include commented model alternatives for providers that have common variants, such as OpenAI mini/nano models.
# Hosted Matrix quickstart (creates ~/.mindroom/config.yaml)
mindroom config init
# Self-hosted Matrix with Anthropic
mindroom config init --matrix-server self-hosted --provider anthropic
# Hosted Matrix with a Codex CLI ChatGPT login
mindroom config init --matrix-server mindroom.chat --provider codex
# Hosted Matrix with Ollama
mindroom config init --matrix-server mindroom.chat --provider ollama
# Hosted Matrix with llama.cpp
mindroom config init --matrix-server mindroom.chat --provider llama.cpp
# Hosted Matrix with Vertex AI Claude
mindroom config init --matrix-server mindroom.chat --provider vertexai_claude
# Preview generated YAML without writing files
mindroom config init --matrix-server mindroom.chat --provider ollama --print
# Force overwrite existing config
mindroom config init --force
Use --print to preview the generated config.yaml in the terminal with YAML syntax highlighting.
It does not create or modify config.yaml, .env, or starter workspace files.
The --provider codex preset generates provider: codex with id: gpt-6-astra and context_window: 258000.
They set extra_kwargs.reasoning_effort: medium.
Prompt caching is enabled automatically per active agent session; leave prompt_cache_key unset unless you intentionally want to override the derived key.
Run codex login first so MindRoom can read ~/.codex/auth.json.
The --provider kimi preset generates provider: kimi with id: k3 and context_window: 1048576.
Run kimi and /login first so MindRoom can read ~/.kimi-code/credentials/kimi-code.json.
The --provider ollama preset generates provider: ollama with id: gemma4, an additional qwen3_8_27b model using qwen3.8:27b, and OLLAMA_HOST=http://localhost:11434.
Pull both local models before running MindRoom:
The --provider llama.cpp preset generates OpenAI-compatible local server config for Unsloth GGUF models.
Start llama.cpp with one of the configured model refs before running MindRoom:
llama-server -hf unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q4_K_M --host 127.0.0.1 --port 8080
llama-server -hf unsloth/Qwen3.8-27B-GGUF:UD-Q4_K_XL --host 127.0.0.1 --port 8080
config show
Display the current config file with syntax highlighting.
# Show config with syntax highlighting
mindroom config show
# Print raw YAML (useful for piping)
mindroom config show --raw
# Show config at a specific path
mindroom config show --path /custom/path/config.yaml
config edit
Open config.yaml in your default editor.
Editor preference: $EDITOR → $VISUAL → nano → vim → vi.
config validate
Validate config.yaml and check for common issues.
Parses the YAML config using Pydantic and reports errors in a friendly format.
Also checks whether required API keys are set as environment variables.
config path
Show the resolved config file path and all search locations.
config resolve
Print the fully merged YAML after recursively resolving every !include tag.
Keys are sorted so the output can be diffed before and after splitting a configuration into include files.
config fingerprint and config check-applied
Confirm that the running runtime finished applying a particular config source:
mindroom config fingerprint --path ./config.yaml
mindroom config check-applied --path ./config.yaml --wait 300
mindroom config check-applied --fingerprint <sha256> --url https://example.org --json
fingerprint hashes the source bytes captured by the YAML loader, including all transitively included YAML and text files.
A single file uses its plain SHA-256; multiple files combine their relative paths and content hashes.
Moving the same tree to another directory preserves its fingerprint.
Comments and formatting changes affect the fingerprint; unrelated files and environment variables do not.
Legacy access settings must be migrated with mindroom config migrate --path <config-path> before capturing a fingerprint.
When reading a config file, both commands reject legacy access settings with exit 2: automatic migration would rewrite their source bytes during reload.
Explicit --fingerprint skips reading local config sources; the caller must supply a fingerprint of the migrated source.
check-applied captures the expected fingerprint once before polling the authenticated GET /api/config/reload-status endpoint.
It requires MINDROOM_API_KEY and HTTPS for remote endpoints.
Without --wait, it checks once.
--timeout bounds each HTTP request; --wait bounds the polling period.
Neither command changes config or triggers a reload.
Exit codes are 0 for matching completed application, 1 for pending or a different fingerprint (including wait expiration), and 2 for matching failure, restart required, or unavailable status.
JSON output identifies the expected and observed fingerprints.
Only the latest reload result is retained in memory.
The runtime acknowledges a fingerprint after its reload plan finishes, including changes that need no agent restart.
A loaded API config cache does not count as completion.
Known event-journal changes requiring a process restart return restart_required.
Completion does not guarantee that every bot or external service is healthy.
If parsing fails before the include tree is known, the failure has no fingerprint and cannot settle a wait for a particular fingerprint.
connect
Pair this local MindRoom install with a provisioning service.
Default provisioning URL is https://mindroom.chat unless you override it with --provisioning-url or MINDROOM_PROVISIONING_URL.
On success (default --persist-env), this writes to .env next to config.yaml:
MINDROOM_PROVISIONING_URLMINDROOM_LOCAL_CLIENT_IDMINDROOM_LOCAL_CLIENT_SECRETMINDROOM_NAMESPACE
If your config still contains the owner placeholder token __MINDROOM_OWNER_USER_ID_FROM_PAIRING__, connect will auto-replace it in membership access and managed-room policy settings when pairing returns a valid owner_user_id.
Use --no-persist-env if you want to export variables only for the current shell session.
Use --provisioning-url for non-default deployments:
local-stack-setup
Start local Synapse and the MindRoom Chat client container for development.
By default this command also writes MATRIX_HOMESERVER, MATRIX_SERVER_NAME, and MATRIX_SSL_VERIFY=false into .env next to your active config.yaml so mindroom run works without inline env exports.
Usage: root local-stack-setup [OPTIONS]
Start local Synapse + MindRoom Chat using Docker only.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --synapse-dir PATH Directory │
│ containing Synapse │
│ docker-compose.yml │
│ (from │
│ mindroom-stack │
│ settings). │
│ [default: │
│ local/matrix] │
│ --homeserver-url TEXT Homeserver URL that │
│ 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. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
trigger
Send signed external trigger requests from cron jobs and watcher scripts.
Usage: root trigger [OPTIONS] COMMAND [ARGS]...
Send signed external triggers.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ keygen Generate an Ed25519 trigger signing key. │
│ send Send a signed external trigger request. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
trigger keygen
Generate an Ed25519 signing key pair for an external trigger.
Usage: root trigger keygen [OPTIONS]
Generate an Ed25519 trigger signing key.
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --private-key-file PATH Path where the base64 raw Ed25519 private key should │
│ be written. │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
trigger send
Send one signed trigger request to MindRoom.
Usage: root trigger send [OPTIONS] TRIGGER_ID
Send a signed external trigger request.
╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮
│ * trigger_id TEXT Configured external trigger id. [required] │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ * --key-file FILE Base64 raw Ed25519 private key file. │
│ [required] │
│ * --kind TEXT Trigger payload kind. [required] │
│ * --message TEXT Trigger payload message. [required] │
│ --event-id TEXT Optional idempotency event id. │
│ --title TEXT Optional trigger title. │
│ --thread-key TEXT Optional key; deliveries sharing it │
│ land in one Matrix thread on new_thread │
│ triggers. │
│ --data-json TEXT Optional JSON object for trigger data. │
│ --timeout FLOAT HTTP request timeout in seconds. │
│ [default: 10.0] │
│ --verify-tls --no-verify-tls Verify TLS certificates. │
│ [default: verify-tls] │
│ --url TEXT MindRoom base URL. │
│ [env var: MINDROOM_URL] │
│ [default: http://127.0.0.1:8765] │
│ --key-id TEXT Trigger signing key id. │
│ [default: default] │
│ --help -h Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
Examples
Basic run
Debug logging
To debug MindRoom internals without enabling debug logs from every dependency, keep the global level at INFO and set targeted logger overrides:
LOG_LEVEL=INFO MINDROOM_LOGGER_LEVELS="mindroom:DEBUG,httpx:WARNING,httpcore:WARNING,anthropic:INFO,nio:WARNING" mindroom run
Matrix crypto decrypt warnings from nio.crypto are quieted by default because missing Megolm sessions can produce bursts of diagnostically useful but high-volume logs.
To inspect those warnings while debugging encryption state, explicitly restore that logger: