# CLI reference

```
omarchy-spaces list                 every space, active one marked
omarchy-spaces current [--json]     the active space id
omarchy-spaces switch <id>          make a space active
omarchy-spaces next | prev          cycle
omarchy-spaces status [--json]      the policy in effect right now
omarchy-spaces open <url>           open a url in the active space's browser
omarchy-spaces which [url]          print the argv `open` would run
omarchy-spaces get <field>          read a field off the active space
omarchy-spaces init [--force]       write a starter config
omarchy-spaces validate             check for gaps, overlaps, bad references
omarchy-spaces install-menu         add the space rows to the Omarchy menu
omarchy-spaces remove-menu          take them back out
omarchy-spaces menu                 print the rows without writing anything

omarchy-spaces workspace <n>            go to slot n of the active space
omarchy-spaces move-to-workspace <n>    move the focused window to slot n
omarchy-spaces move-to-space <id> [n]   send the focused window to another space
omarchy-spaces windows                  list open windows grouped by space

omarchy-spaces startup show [space]     what each workspace opens
omarchy-spaces startup capture [slot]   record the workspace you are on
omarchy-spaces startup run [space][slot] open it
omarchy-spaces startup enable|disable   a space, or one slot
omarchy-spaces startup forget [slot]    drop a slot, or the whole layout

omarchy-spaces appearance show          pinned look vs the live one
omarchy-spaces appearance capture       save the current theme, font, background
omarchy-spaces appearance apply         re-apply the pinned look
omarchy-spaces appearance clear         stop pinning a look

omarchy-spaces discover browsers        installed browsers
omarchy-spaces discover profiles <cmd>  that browser's profiles
omarchy-spaces discover apps            app names this machine knows about
omarchy-spaces discover themes          omarchy theme list
omarchy-spaces discover fonts           omarchy font list
omarchy-spaces discover backgrounds     the current theme's backgrounds
```

## discover

Every `discover` subcommand prints JSON. The configuration app uses them to
fill its dropdowns instead of asking you to type a browser name or a theme, and
they are on the CLI so scripts get the same lists.

```bash
omarchy-spaces discover browsers
omarchy-spaces discover profiles brave
```

```json
[ { "command": "brave", "name": "Brave", "desktop": "brave-browser.desktop", "chromium": true } ]
[ { "directory": "Default", "name": "Samy Perso", "email": "", "active_time": 1787536682 } ]
```

`browsers` groups several desktop files that run the same executable and picks
the most canonical name, so a per-profile launcher does not end up labelling
the browser itself.

`profiles` returns nothing for a browser that is not Chromium-family, since
`--profile-directory` is a Chromium flag. It also skips entries whose directory
is missing from disk, which happens after a profile is deleted or a launcher
passes a malformed profile name.

`apps` labels each name by where it came from. Names seen in notification
history rank first, because that is literally the string the matching compares
against.

## get

Reads any top level field off the active space, plus assistant accounts through
a dotted key.

```bash
omarchy-spaces get email            # you@company.com
omarchy-spaces get name             # HiScale
omarchy-spaces get assistant.codex  # work
```

Unknown fields print an empty line rather than failing, so it is safe in a
shell prompt.

## Scripting

```bash
# git identity that follows the space
git config user.email "$(omarchy-spaces get email)"

# only run something in one space
[ "$(omarchy-spaces current)" = "work" ] && ./deploy.sh

# is anything muted right now
omarchy-spaces status --json | python3 -c "
import json,sys
p=json.load(sys.stdin)['policy']
print('muted' if not p['allowFrom'] and not p['allowUnassigned'] else 'allowing ' + ', '.join(p['allowFrom']))
"
```

## Exit codes

`0` on success. `1` on a usage error or a failed `validate`. `2` when the config
is missing or unparseable.

`validate` returning 1 means it printed warnings, not that the config is
unusable.

## Why python

The CLI is python3 rather than node because Hyprland keybindings and desktop
handlers run with a minimal PATH. python3 is always present on Omarchy, a mise
managed node may not resolve.

The policy rules therefore exist twice, in `bin/omarchy-spaces` and in
`SpacesLogic.js` for the shell plugin. `test/parity.sh` runs both across every
minute of the day for every space and fails if a single decision differs.