AEROSPACE-LIST-WORKSPACES(1)

📦 version 0.21.3-Beta, in nixpkgs unstable

💅 aerospace-list-workspaces(1) — from the AeroSpace Manual, bestie

okay so you opened the manual page for aerospace-list-workspaces and honestly? good for you. this is the AeroSpace Manual, section 1, and we're about to go through the whole thing together, no skips, no "you can read the rest later", we're doing this 💖

✨ NAME ✨

aerospace-list-workspaces — prints out the workspaces that satisfy your conditions, literally that's the whole job and she does it beautifully 🎀

🦋 SYNOPSIS 🦋

aerospace list-workspaces [-h|--help] --monitor <monitor>... [--visible [no]] [--empty [no]] [--format <output-format>] [--count] [--json]
aerospace list-workspaces [-h|--help] --all [--format <output-format>] [--count] [--json]
aerospace list-workspaces [-h|--help] --focused [--format <output-format>] [--count] [--json]

three whole shapes, pick your fighter 🌸

🌈 DESCRIPTION 🌈

Print workspaces that satisfy conditions. that's it. that's the vibe. she lists workspaces, you vibe check them, everyone goes home happy ✨

👑 OPTIONS 👑

  • -h, --help — prints the help. iconic, classic, we love a self-documenting queen 🫶
  • --format <output-format> — tells her exactly how you want the output shaped. peek the "Output Format" section down below for the full tea 💅
  • --all — an alias for --monitor all. and bestie, please use this one with caution. use it when you really need to get workspaces/windows from all monitors.

for a multi-monitor setup, --monitor focused is almost always the preferred option. the way that automation should not be messing up your workspaces/windows on a completely different monitor, fr fr.

with great power comes great responsibility. no cap. 😭

  • --focused — an alias for --monitor focused --visible. always prints exactly one workspace. single. solo. main character energy 👑
  • --monitor <monitors> — filters results so you only print workspaces/windows attached to the monitors you named. <monitors> is a space separated list of monitor IDs.

the possible monitor IDs are:

  1. a 1-based index of a monitor, as if the monitors were ordered horizontally from left to right
  2. all — a special monitor ID that represents all monitors
  3. mouse — a special monitor ID that represents the monitor with the mouse
  4. focused — a special monitor ID that represents the focused monitor
  • --visible [no] — filters results to only print currently visible workspaces. [no] inverts the condition. and yes, several workspaces can be visible in a multi-monitor setup 🌸
  • --empty [no] — filters results to only print empty workspaces. [no] inverts the condition 🍓
  • --format <output-format> — specify the output format. see the "Output Format" section for more details. incompatible with --count 🚫
  • --count — outputs only the number of workspaces. incompatible with --format 💀
  • --json — outputs in JSON format. can be used in combination with --format to specify which data gets included into the json. incompatible with --count 🔥

🧚 OUTPUT FORMAT 🧚

the output format is configurable with the optional [--format <output-format>] option. <output-format> supports string interpolation — yes, like [that wikipedia article](https://en.wikipedia.org/wiki/String_interpolation) but you already knew that, iykyk 💜

if you don't specify anything, the default <output-format> is:

%{workspace}

the following variables can be used inside <output-format>:

  • %{workspace} — String. the name of the belonging workspace 💖
  • %{workspace-is-focused} — Boolean. true if the workspace has focus 👑
  • %{workspace-is-visible} — Boolean. true if the workspace is visible. a workspace can be visible but not focused in a multi-monitor setup 🌈
  • %{workspace-root-container-layout} — String. the layout (v_tiles, h_tiles, v_accordion, h_accordion) of the workspace's root container 🧩
  • %{monitor-id} — 1-based Number. the sequential number of the belonging monitor ⭐
  • %{monitor-appkit-nsscreen-screens-id} — 1-based Number. the sequential number of the belonging monitor in NSScreen.screens. useful for integration with other tools that might be using NSScreen.screens ordering (like sketchybar) 🦋
  • %{monitor-name} — String. the name of the belonging monitor 🎀
  • %{monitor-is-main} — Boolean. true if the monitor is main 🌸
  • %{right-padding} — a special variable which expands with a minimum number of spaces required to form a right padding in the appropriate column. yes she formats, yes she slays 💅
  • %{newline} — the Unicode U+000A newline symbol \n 😭
  • %{tab} — the Unicode U+0009 tab symbol \t 🙈

🔥 RESOURCES 🔥

go read the guide, she ate 💖

💀 BUGS 💀

bugs can be reported to https://github.com/nikitabobko/AeroSpace/discussions/categories/potential-bugs

maintainers will move verified bugs to https://github.com/nikitabobko/AeroSpace/issues 🫶

🌟 LICENSE 🌟

Copyright © 2023 Nikita Bobko

free use of this software is granted under the terms of the MIT License. you can find the full text of the AeroSpace license and its dependencies in the legal directory of the distributed zip archive ⭐

💜 AUTHOR 💜

Nikita Bobko and contributors 👑

ok that's literally the whole page, bestie. go forth and list-workspaces responsibly (remember: with great power comes great responsibility) 😌

AeroSpace, dated 2026-07-16 — mwah, big kiss, this manual page for aerospace-list-workspaces(1) is officially done 🎀💅✨

📦 where this page comes from