Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

CLI Commands

All interactions with Mosaico go through the command-line interface.

mosaico init

Creates default configuration files in ~/.config/mosaico/:

  • config.toml – layout, border, theme, and logging settings
  • keybindings.toml – keyboard shortcuts
  • rules.toml – community window rules (auto-updated on daemon startup)
  • user-rules.toml – personal rule overrides
  • bar.toml – status bar settings

Files that already exist are skipped to preserve your customizations. The daemon writes any missing files when it starts too. On first run, you are prompted to enable automatic startup. That includes running init after the daemon wrote the files, as long as config.toml is unchanged and autostart was never set up.

mosaico start

Launches the daemon as a detached background process. On success, a startup banner is printed showing the config directory, PID, and a usage tip. If a newer release is available on GitHub, an update notice is shown.

If the daemon is already running, the command reports the existing state instead of starting a second instance.

mosaico start --quiet prints nothing and skips the update check. Automatic startup uses it so signing in never waits on the network.

mosaico stop

Sends a stop command to the running daemon. All windows are restored to their original positions before the daemon exits. If the daemon is unresponsive, a fallback mechanism terminates the process directly.

mosaico status

Reports whether the daemon is running, along with its PID. Detects and cleans up stale PID files from crashed sessions.

mosaico doctor

Runs a comprehensive health check and prints colored status tags for each item:

TagMeaning
[ok]Check passed
[warn]Non-critical issue
[fail]Critical problem
[fixed]Auto-remediated

Checks performed:

  1. Config directory exists (creates it if missing)
  2. config.toml syntax validation, and each value it holds that mosaico does not take as written: a number out of its range, a name it does not list, or a key that is no setting, named as the settings window names it
  3. Theme flavor validation
  4. keybindings.toml syntax validation
  5. Key names resolve to valid key codes
  6. rules.toml syntax validation
  7. Community rules cache age
  8. user-rules.toml syntax validation, and a warning when its rules still use the deprecated manage
  9. bar.toml syntax validation, its values checked as for config.toml, how many click bindings the bar has, and each one it ignores, with why
  10. Autostart status: warns when the startup entry starts another copy of mosaico or other arguments, or is turned off, fails when the program it starts no longer exists
  11. Daemon status (IPC pipe, PID file, process liveness)
  12. Monitor enumeration and dimensions
  13. Window transitions: the [animations] settings (the defaults when config.toml is invalid, and it says so), whether Windows allows animations right now (“Animation effects”, and not a remote session), and whether windows can move frame by frame; warns when transitions are enabled but windows would snap into place anyway, and says why

mosaico autostart

Manages automatic startup when Windows boots.

mosaico autostart enable    # Register to start on logon
mosaico autostart disable   # Remove the startup entry
mosaico autostart status    # Show current autostart state

This registers a task in the Windows Task Scheduler that runs mosaico start --quiet when you sign in. It runs as you, so no administrator rights are needed, and at normal priority, as soon as you sign in. Programs listed under Settings > Apps > Startup start later: Windows waits before it runs them, then starts them one at a time.

The entry starts the mosaico.exe you ran enable with. If you move the binary, or install another copy, the entry keeps pointing at the old one: mosaico autostart status and mosaico doctor say so, and running mosaico autostart enable again from the right copy fixes it.

Disabling the task in Task Scheduler (it is named Mosaico autostart for <your SID>) keeps it but stops it from running at sign-in. mosaico autostart status and mosaico doctor report that too, and mosaico autostart enable turns it back on.

Releases before this one registered autostart in the registry Run key, under Startup apps. mosaico autostart status and mosaico doctor report such an entry as starting other arguments. Run mosaico autostart enable once to replace it with the task.

On first run, mosaico init also prompts to enable autostart.

mosaico settings

Opens the settings window. It starts mosaico-settings.exe, which is installed beside mosaico.exe, and returns at once. The daemon does not need to be running.

mosaico settings

If the settings app is missing, for example after an update from a release that did not ship it, run mosaico update --force to install it.

mosaico update

Checks GitHub for a newer release and installs it automatically, together with the settings app. If the daemon is running, it is stopped before the update and restarted afterward. An open settings window keeps running the old version until you close it.

When mosaico was installed with the MSI, by winget or the install script, the update downloads the release’s MSI and runs it, so the installed version shown in Installed apps stays right. The command returns while the installer runs; the installer stops and restarts the daemon. A copy outside the installer’s folder replaces its own files instead.

mosaico update          # Update to the latest release
mosaico update --force  # Reinstall even if already on the latest version

The --force flag is useful for recovering a corrupted binary.

mosaico action <verb> [direction]

Sends a tiling action to the running daemon. Available actions:

mosaico action focus left|right|up|down
mosaico action move left|right|up|down
mosaico action retile
mosaico action toggle-monocle
mosaico action toggle-float
mosaico action cycle-float
mosaico action grow-width|shrink-width|grow-height|shrink-height
mosaico action close-focused
mosaico action cycle-layout
mosaico action go-to-workspace <1-8>
mosaico action go-to-workspace-next
mosaico action go-to-workspace-prev
mosaico action send-to-workspace <1-8>

These are the same actions triggered by keyboard shortcuts, useful for scripting or integration with other tools. In keybindings.toml the workspace actions carry the number in their name instead: goto-workspace-N and send-to-workspace-N (see Keyboard Bindings). The steps to the next and previous workspace also go by their key binding names, goto-workspace-next and goto-workspace-prev.

mosaico pause / mosaico unpause

Temporarily suspends all mosaico global hotkeys so another application can use those key combinations, then restores them.

mosaico pause     # Unregister all hotkeys (releases them to the OS)
mosaico unpause   # Re-register all hotkeys

While paused, the status bar shows a red PAUSED indicator. You can also toggle pause from the keyboard by binding the toggle-pause action — the toggle hotkey remains registered while paused so you can resume without opening a terminal. See Keyboard Bindings for setup.

mosaico banner

Plays the animated Mosaico logo that mosaico start shows.

mosaico debug list

Displays a formatted table of all visible windows showing:

  • HWND (hex)
  • Managed status
  • Monitor number
  • Title and class name
  • Position and dimensions
  • Border offset

mosaico debug events

Streams real-time window events to stdout. Press Ctrl+C to stop. Useful for understanding how Mosaico reacts to window changes.

mosaico debug move --window <id> --x <x> --y <y> --w <width> --h <height>

Moves a specific window to exact pixel coordinates. The id is the one mosaico debug list shows (0x hex), or the same number in decimal; --hwnd still works in place of --window. Useful for testing window positioning.

mosaico debug state

Prints the running daemon’s view of your desktop: each monitor, its workspaces that have windows and the windows on them, the monitors that were disconnected, and which monitor and window have focus. Useful for checking what Mosaico manages and where.