命令列

使用 groupshelf 指令，可以在「終端機」或腳本中將開啟的視窗分組、將視窗加入群組或解散群組，以及列出視窗。GroupShelf 1.3.0 及以後版本隨附此指令。

安裝

該指令包含在 GroupShelf.app 中。安裝它，就是在 PATH 中的某個檔案夾裡建立指向它的連結。

如果使用 Homebrew，安裝 GroupShelf 時會自動為你連結該指令：

brew install --cask alpharium-tech/tap/groupshelf

如果你在 1.3.0 之前透過 Homebrew 安裝了 GroupShelf，在 App 內更新不會加入該連結。請執行一次以下指令：

brew reinstall --cask groupshelf

如果不使用 Homebrew，GroupShelf 的設定 › 命令列會顯示建立連結的指令，可直接拷貝。在「終端機」中執行它，系統會要求輸入你的 Mac 密碼。對於「應用程式」檔案夾中的 GroupShelf，指令如下：

sudo mkdir -p /usr/local/bin && sudo ln -sf '/Applications/GroupShelf.app/Contents/Helpers/groupshelf' /usr/local/bin/groupshelf

只有當 GroupShelf 位於「應用程式」檔案夾並從該處打開時，設定中才會提供該指令：指向「下載項目」檔案夾中拷貝的連結，會在 App 移動後失效。

安裝完成後，設定 › 命令列會顯示它的安裝位置，執行 groupshelf version 會顯示它所屬的 GroupShelf 的版本。

啟用

操作視窗的指令只有在你允許後才能使用：在 GroupShelf 的設定 › 命令列中，開啟「允許透過命令列和腳本控制」。在你開啟之前，它會一直保持關閉。help 和 version 無論是否開啟都能使用。

開啟期間，你允許控制 GroupShelf 的 App（例如終端機 App）以及其中執行的任何程式，都可以將視窗分組，並讀取此桌面上所有視窗的標題。

權限

首次使用時，macOS 會詢問是否允許你的終端機 App 控制 GroupShelf，指令會等待你的回答。如果你選擇了不允許，請在系統設定 › 隱私權與安全性 › 自動化中，開啟你的終端機 App 底下的 GroupShelf。

Visual Studio Code

VS Code 的 Universal 版本（大多數人下載的版本，1.104 及以後版本）缺少 macOS 詢問此權限前所需的項目。macOS 會不經詢問直接拒絕，也不會在 Visual Studio Code 底下列出 GroupShelf，因此 groupshelf 會讓 macOS 照樣詢問。它會顯示下面這行，對話框中會出現 Visual Studio Code 的名稱：

groupshelf: asking macOS whether your terminal app may control GroupShelf…

回答一次後，之後就能一直使用。如果在「自動化」中 Visual Studio Code 底下仍未列出 GroupShelf，請改為安裝 VS Code 的 Apple silicon 或 Intel 版本，而不是 Universal 版本：這兩個版本都帶有該項目。Homebrew 的 visual-studio-code cask 會安裝適合你 Mac 晶片的版本。

指定視窗

指令中凡是接受 <window> 的地方，都可以用以下三種方式之一來寫。含有空格的內容請加上引號。

將一個 App 寫兩次，即可使用它的兩個視窗。

如果一個標題符合多個視窗，就會出錯，除非你加上 --frontmost（使用其中最前面的視窗）或 --all（全部使用）。對於未指定標題的 App，--all 也會使用它的所有視窗。

groupshelf 從不打開 App，因此 App 必須已在執行。group 和 add 會等待執行中 App 的視窗出現，最長 30 秒，所以剛剛打開的 App 也能使用：

open -a Safari && open -a Terminal && groupshelf group Safari Terminal

只有此桌面上的視窗才算在內，包括縮到最小的視窗。全螢幕視窗有自己的桌面，因此不算在內。

相對路徑以目前的檔案夾為基準。若要為路徑加上標題，請寫在 .app: 之後，例如 /Applications/Safari.app:Docs。

指令

groupshelf help 會列出所有指令，groupshelf help <command> 會說明其中一個。如果 GroupShelf 未在執行，指令會在背景啟動它，但絕不會打開你指定的 App。

選項可以放在 -- 之前的任何位置，其值接在空格或 = 之後：--name Work 或 --name=Work。名稱以 - 開頭的 App 請放在 -- 之後。

group

groupshelf group [--name <name>] [--all | --frontmost] <window> <window>...

依指定的順序將視窗合併為一組標籤頁。第一個視窗決定群組的位置和大小，完成後會顯示它的標籤頁。已在其他群組中的視窗會離開原本的群組，加入這個群組。

至少需要兩個視窗，使用 --all 時一個 <window> 即可。如果有視窗在 30 秒內沒有出現，就用其餘視窗組成群組，並回報缺少的視窗。對正好由這些視窗組成的群組執行時，只會依指定順序排列標籤頁。

選項
--name <name>
為新群組命名，以便之後用 --group 找到它。
--frontmost
當一個標題符合多個視窗時，使用最前面的那個。
--all
使用所有符合的視窗：App 的所有視窗，或包含該標題的所有視窗。
範例
groupshelf group Safari Terminal Notes Mailgroupshelf group --name Work Code:proj-a Terminal:proj-a Safariopen -a Safari && open -a Terminal && groupshelf group Safari Terminalgroupshelf group --all Terminal

add

groupshelf add [--all | --frontmost] --group <name> <window>...
groupshelf add [--all | --frontmost] <member> <window>...

將視窗加入此桌面上某個現有群組的末尾，該群組的位置、大小和顯示的標籤頁保持不變。已在其他群組中的視窗會移過來。與 group 一樣，只使用已開啟的視窗，最長等待 30 秒。

用 --group 指定群組，或用群組中的一個視窗來指定（<member>，寫法與 <window> 相同）。App，或帶 --frontmost 的標題，會優先使用群組中還沒有的視窗；已在群組中的視窗保持不變。

選項
--group <name>
以名稱指定的群組，不區分大小寫：即透過 --name 設定的名稱，或在其標籤頁列上按一下右鍵並選擇「命名群組⋯」設定的名稱。
--frontmost
當一個標題符合多個視窗時，使用最前面的那個。
--all
使用所有符合的視窗：App 的所有視窗，或包含該標題的所有視窗。
範例
groupshelf add --group Work Slackgroupshelf add Code:proj-a Terminal:proj-a

detach

groupshelf detach [--all | --frontmost] <window>...

將視窗從所在的群組分離；只剩一個視窗的群組會解散。不會打開任何東西，也不會等待：視窗必須已在此桌面上。不在任何群組中的視窗保持不變。

選項
--frontmost
當一個標題符合多個視窗時，使用最前面的那個。
--all
使用所有符合的視窗：App 的所有視窗，或包含該標題的所有視窗。
範例
groupshelf detach Slack

ungroup

groupshelf ungroup [--group <name>]... [<member>]...

解散群組，視窗留在原處。用 --group 指定群組（多個群組就重複使用），或用群組中的一個視窗來指定（<member>，寫法與 <window> 相同）。不在任何群組中的視窗會被略過。只要有一個找不到，就不會解散任何群組。

選項
--group <name>
以名稱指定的群組，不區分大小寫：即透過 --name 設定的名稱，或在其標籤頁列上按一下右鍵並選擇「命名群組⋯」設定的名稱。
範例
groupshelf ungroup --group Workgroupshelf ungroup Code:proj-a

list

groupshelf list

依從前到後的順序列出此桌面上可以分組的視窗，縮到最小的視窗排在最後。GroupShelf 自己的視窗和被排除 App 的視窗不會列出。每一行對應一個視窗，包含以下以定位字元分隔的欄位，沒有標題列：

  1. 視窗 ID
  2. App 名稱
  3. 標題
  4. 群組編號（沒有則為空）
  5. 群組名稱（沒有則為空）
  6. minimized（未縮到最小則為空）
groupshelf list4211	Safari	GroupShelf — Command line	1	Work	4198	Terminal	proj-a — zsh	1	Work	4305	Mail	Inbox			3977	Notes	Shopping			minimized

標題中的定位字元或換行字元會變成空格，因此欄位一律對齊。ID 可以用作其他指令的 <window>；搭配 fzf，可以挑選視窗並將它們分組：

範例
groupshelf list | fzf -m | cut -f1 | xargs groupshelf group

help

groupshelf help [<command>]

顯示指令列表，或其中一個指令的用法：group、add、detach、ungroup 或 list。

範例
groupshelf help group

version

groupshelf version

顯示指令所隨附的 GroupShelf 的版本和建置編號。兩者一律是同一個建置。

結束狀態

腳本可以依結束狀態進行分支處理。訊息會輸出到標準錯誤，且都以 groupshelf: 開頭。

0
成功。
1
GroupShelf 回報了錯誤：需要修改要求，例如某個 App 沒有在執行。缺少部分視窗而組成的群組也算在內。
2
用法錯誤：命令列本身有誤。指令會說明錯在哪裡並顯示其用法，不會聯絡 GroupShelf。
3
無法聯絡 GroupShelf：需要修正設定，例如缺少某項權限。

疑難排解

每則訊息的含義及處理方式。其中的名稱和數字只是範例，實際會顯示你輸入的內容。

聯絡 GroupShelf · 結束狀態 3

groupshelf: GroupShelf.app not found

指令找不到它所隨附的 GroupShelf：它是存放在 App 之外的拷貝，而且沒有安裝 GroupShelf。請安裝 GroupShelf，然後依照「安裝」中的方式連結該指令，而不是拷貝它。

groupshelf: GroupShelf could not be launched: <reason>

GroupShelf 沒有在執行，macOS 也因所示原因無法打開它。請自行打開 GroupShelf，然後再次執行該指令。

groupshelf: GroupShelf did not start within 15 seconds

GroupShelf 已在背景打開，但沒有及時準備就緒。請再次執行該指令。

groupshelf: GroupShelf did not answer in time; if macOS asked whether your terminal app may control GroupShelf, answer that and try again

這通常是因為 macOS 仍在等待你回答權限詢問。請回答後再次執行該指令。

groupshelf: not allowed to control GroupShelf; allow your terminal app in System Settings › Privacy & Security › Automation

你的終端機 App 不能控制 GroupShelf。請在系統設定 › 隱私權與安全性 › 自動化中，開啟你的終端機 App 底下的 GroupShelf。

groupshelf: if Visual Studio Code doesn't list GroupShelf there, install VS Code's Apple silicon or Intel build; its Universal build can't ask macOS for this permission

在 VS Code 的終端機中，這一行會緊接在上一行之後出現。請參閱「權限」中的 Visual Studio Code 部分。

groupshelf: this version of GroupShelf doesn't support groupshelf; update GroupShelf

指令聯絡到的 GroupShelf 早於該指令，例如 Mac 上其他位置的舊拷貝。請將 GroupShelf 更新到 1.3.0 或以後版本，並刪除所有舊拷貝。

groupshelf: could not reach GroupShelf (error <number>)

macOS 因其他原因無法傳遞要求；數字是它的錯誤代碼。請結束並重新打開 GroupShelf，然後再試一次。如果問題持續發生，請附上該數字聯絡支援。

GroupShelf 的設定和狀態 · 結束狀態 1

groupshelf: control from the command line is off; turn on "Allow control from the command line and scripts" in GroupShelf Settings › Command Line

依照「啟用」中的說明，開啟設定 › 命令列中的開關。

groupshelf: GroupShelf needs Accessibility access; allow it in System Settings › Privacy & Security › Accessibility

沒有這項權限，GroupShelf 就無法移動視窗。請在系統設定 › 隱私權與安全性 › 輔助使用中開啟 GroupShelf。

groupshelf: GroupShelf is paused while Stage Manager is on

GroupShelf 不能與幕前調度同時使用。請在系統設定中關閉幕前調度，然後重新啟動 GroupShelf。

groupshelf: GroupShelf hasn't finished starting; try again

請稍候片刻後再次執行該指令。

groupshelf: another group request is still running

GroupShelf 一次只處理一個要求，而 group 和 add 可能會等待視窗最長 30 秒。請在另一個要求完成後再次執行。

groupshelf: "Slack" is excluded from grouping in GroupShelf settings

該 App 位於設定 › 分組中的「排除的 App」裡。若要將它的視窗分組，請從該處移除它。

指定視窗 · 結束狀態 1

groupshelf: "Safari" isn't running; open it first — groupshelf only works with windows already open

請先打開該 App。之後 group 和 add 會等待它的視窗出現，最長 30 秒。

groupshelf: no application named "Safary"

請檢查拼字。未在執行且不在「應用程式」檔案夾中的 App，只能用它的 Bundle ID 或路徑來指定。

groupshelf: "/Applications/Utilities" is not an application

該路徑指向的不是 App。請讓它指向 .app 本身。

groupshelf: "Terminal:proj" fits 2 windows ("proj-a — zsh", "proj-b — zsh"); give more of the title, a window ID from groupshelf list, or --frontmost or --all

有多個視窗的標題包含這段文字。請用訊息中列出的方式之一縮小範圍。

groupshelf: no window 4211 on this desktop; groupshelf list shows the windows there

該視窗已關閉，或在另一個桌面上，或處於全螢幕狀態。請執行 groupshelf list 查看目前的 ID。

groupshelf: no window for "Slack" on this desktop

detach、ungroup 和 <member> 只看此桌面上已有的視窗，不會等待。請確認該視窗在這裡是開啟的。

groupshelf: "4211" names a window another argument already names

有兩個引數指向同一個視窗。請刪除其中一個。

groupshelf: GroupShelf can't group its own windows

請不要在指令中指定 GroupShelf。

指定群組 · 結束狀態 1

groupshelf: no group named "Work"

沒有群組使用這個名稱。groupshelf list 的第五個欄位會顯示每個視窗所在群組的名稱。

groupshelf: --group "Work" fits 2 groups; name the group by one of its windows instead

有多個群組使用這個名稱。請改用群組中的一個視窗作為 <member> 來指定該群組。

groupshelf: the group of "Work" isn't on this desktop

add 只能將視窗加入此桌面上的群組。請前往該群組所在的桌面，在那裡執行。

groupshelf: "Safari" isn't in a group; groupshelf group makes one

作為 <member> 指定的視窗不在任何群組中。請用 group 建立一個群組。

部分完成 · 結束狀態 1

groupshelf: grouped 3 windows; no window for "Mail" on this desktop within 30 seconds
groupshelf: added 1 window; no window for "Mail" on this desktop within 30 seconds
groupshelf: nothing added; no window for "Mail" on this desktop within 30 seconds

第一個分號之前的內容已經完成。分號之後列出的視窗沒有包含進來：它們在 30 秒內都沒有出現在此桌面上。

groupshelf: no group created: only 1 window to group; no window for "Mail" on this desktop within 30 seconds

找到的視窗不足兩個，因此沒有做任何變更。

groupshelf: grouped 2 windows; "Mail" could not be added to the group

該視窗所在的群組或它要加入的群組已被鎖定。請在被鎖定群組的標籤頁列上按一下右鍵，選擇「解鎖群組」，然後再次執行該指令。

用法錯誤 · 結束狀態 2

groupshelf: unknown option '--names'
Usage: groupshelf group [--name <name>] [--all | --frontmost] <window> <window>...
Run 'groupshelf help group' for more.

命令列本身有誤：第一行說明錯在哪裡，後面是該指令的用法。沒有傳送任何內容給 GroupShelf。

← 返回首頁