AEROSPACE-LIST-WINDOWS(1)

📦 version 0.21.3-Beta, in nixpkgs unstable

🪟 AEROSPACE-LIST-WINDOWS 💅

okay so bestie, this is a page from the AeroSpace Manual — aerospace-list-windows(1), to be exact. Buckle up, we're listing windows ✨

🌸 NAME 🌸

aerospace-list-windows — print windows that satisfy conditions. that's it. that's the whole job. she's an icon, she's a legend, and she is literally the question "which windows tho?" 🫶

🎀 SYNOPSIS 🎀

aerospace list-windows [-h|--help] (--workspace <workspace>...|--monitor <monitor>...)
                       [--monitor <monitor>...] [--workspace <workspace>...]
                       [--pid <pid>] [--app-bundle-id <app-bundle-id>] [--format <output-format>]
                       [--count] [--json]
aerospace list-windows [-h|--help] --all [--format <output-format>] [--count] [--json]
aerospace list-windows [-h|--help] --focused [--format <output-format>] [--count] [--json]

three whole vibes to pick from, pick your fighter 💖

✨ DESCRIPTION ✨

Print windows that satisfy conditions 💅 no cap, that is the entire mission statement. you give her conditions, she gives you windows. match made in heaven.

🔥 OPTIONS 🔥

  • -h, --help — print help. the og "what does this do again" button 🎀
  • --all — alias for --monitor all. and bestie, please use this option with caution 🚨 only reach for it when you really need to get workspaces/windows from all monitors.

for multi-monitor setup, --monitor focused is almost always the preferred option. seriously. if you're automating something, then you do not want to mess up with workspaces/windows on a different monitor. that's how you get chaos in the group chat 😭

with great power comes great responsibility. she said it, not me 🕷️

  • --focused — print the focused window. but heads up bestie: it is possible for no window to be in focus. in that case, error is reported 💀 not me getting an error at the worst possible moment.
  • --workspace <workspace>... — filter results to only print windows that belong to either of specified workspaces. <workspace>... is a space-separated list of workspace names.

possible values:

  1. Workspace name
  2. focused is a special workspace name that represents the focused workspace
  3. visible is a special workspace name that represents all currently visible workspaces (in multi-monitor setup, there are multiple visible workspaces)

three flavors of workspace reference, all iconic 👑

  • --monitor <monitors> — filter results to only print workspaces/windows that are attached to specified monitors. <monitors> is a space separated list of monitor IDs.

possible monitors IDs:

  1. 1-based index of a monitor as if monitors were ordered horizontally from left to right
  2. all is a special monitor ID that represents all monitors
  3. mouse is a special monitor ID that represents monitor with the mouse 🖱️
  4. focused is a special monitor ID that represents the focused monitor

the mouse one is lowkey the moment fr fr 🐭

deprecated (but still supported) flag name: --app-id. she's retired but she still shows up to the party 🎀

  • --format <output-format> — specify output format. see the "Output Format" section for more details. incompatible with --count — pick one, bestie, you can't have both 🙈
  • --count — output only the number of windows. incompatible with --format — same deal, no double dipping. also incompatible with --json (see below) 🔢
  • --json — output in JSON format. can be used in combination with --format to specify which data to include into the json ✨. incompatible with --count 💀
the compatibility rules are giving strict parent energy: --count and --format cannot coexist, and --count and --json cannot coexist. respect the boundaries bestie 🚧

🌈 OUTPUT FORMAT 🌈

output format can be configured with the optional [--format <output-format>] option. <output-format> supports string interpolation <https://en.wikipedia.org/wiki/String_interpolation> ✨

if not specified, the default <output-format> is:

%{window-id}%{right-padding} | %{app-name}%{right-padding} | %{window-title}

the following variables can be used inside <output-format> — collect them all like Pokémon cards 🃏:

  • %{window-id} — Number. Window unique ID
  • %{window-title} — String. Window title
  • %{window-is-fullscreen} — Boolean. Is window in fullscreen by aerospace fullscreen command
  • %{window-layout} — String. An alias for %{window-parent-container-layout}
  • %{window-parent-container-layout} — String. The layout (v_tiles, h_tiles, v_accordion, h_accordion, floating) of the window's parent container.
  • %{app-bundle-id} — String. Application unique identifier. Bundle ID <https://developer.apple.com/documentation/appstoreconnectapi/bundle_ids>
  • %{app-name} — String. Application name
  • %{app-pid} — Number. UNIX process identifier <https://en.wikipedia.org/wiki/Process_identifier>
  • %{app-exec-path} — String. Application executable path
  • %{app-bundle-path} — String. Application bundle path
  • %{workspace} — String. 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 the window belongs to.
  • %{monitor-id} — 1-based Number. Sequential number of the belonging monitor.
  • %{monitor-appkit-nsscreen-screens-id} — 1-based index of the belonging monitor in NSScreen.screens array. useful for integration with other tools that might be using NSScreen.screens ordering (like sketchybar) 🧚
  • %{monitor-name} — String. 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. the alignment queen 👑
  • %{newline} — Unicode U+000A newline symbol \n
  • %{tab} — Unicode U+0009 tab symbol \t

🦋 RESOURCES 🦋

bookmark them, bestie, future you will say thank you 💜

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

so like... discussions first, then issues. the pipeline is real 🎀

👑 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 AeroSpace license and its dependencies in the 'legal' directory of the distributed zip archive.

🌸 AUTHOR 🌸

Nikita Bobko and contributors 💖

that's the whole page, no notes, she ate 💅✨

— with love from the AeroSpace manual, dated 2026-07-16 🎀 (AeroSpace, AEROSPACE-LIST-WINDOWS(1) — catch you in the next manpage, bestie 🦋)

📦 where this page comes from