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. On first run, you are prompted to enable automatic startup.

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 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:

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

Checks performed:

Config directory exists (creates it if missing)
config.toml syntax validation
Theme flavor validation
keybindings.toml syntax validation
Key names resolve to valid key codes
rules.toml syntax validation
Community rules cache age
user-rules.toml syntax validation
bar.toml syntax validation, how many click bindings the bar has, and each one it ignores, with why
Autostart status: warns when the startup entry starts another copy of mosaico or other arguments, or is turned off in the startup apps settings, fails when the program it starts no longer exists
Daemon status (IPC pipe, PID file, process liveness)
Monitor enumeration and dimensions
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 writes a value under the HKEY_CURRENT_USER registry Run key, so no administrator rights are needed.

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.

Turning mosaico off under Settings > Apps > Startup, or in Task Manager’s Startup apps, keeps the entry but stops it from running at logon. mosaico autostart status and mosaico doctor report that too, and mosaico autostart enable turns it back on.

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

`mosaico update`

Checks GitHub for a newer release and installs it automatically. If the daemon is running, it is stopped before the update and restarted afterward.

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 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.

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.

Mosaico