コマンドライン

groupshelf コマンドを使うと、開いているウィンドウのグループ化、グループへの追加や解除、ウィンドウの一覧表示を、ターミナルやスクリプトから行えます。GroupShelf 1.3.0 以降に付属しています。

インストール

コマンドは GroupShelf.app に含まれています。インストールとは、PATH 上のフォルダにコマンドへのリンクを作ることです。

Homebrew を使う場合は、GroupShelf をインストールするとコマンドも自動でリンクされます:

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

1.3.0 より前に Homebrew で GroupShelf をインストールした場合、アプリ内でアップデートしてもリンクは追加されません。次を一度だけ実行してください:

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 を「アプリケーション」フォルダに移動し、そこから開いたときだけです。「ダウンロード」フォルダにあるコピーへのリンクは、アプリを移動すると切れてしまうためです。

インストールが済むと、設定 › コマンドライン にインストール先が表示され、groupshelf version でコマンドが属する GroupShelf のバージョンを確認できます。

オンにする

ウィンドウを操作するコマンドは、許可して初めて使えます。GroupShelf の設定 › コマンドライン で「コマンドラインとスクリプトからの操作を許可」をオンにしてください。オンにするまではオフのままです。help と version はどちらの状態でも使えます。

オンの間は、GroupShelf の制御を許可したアプリ(ターミナルアプリなど)と、そこで動くプログラムが、ウィンドウをまとめたり、このデスクトップのすべてのウィンドウのタイトルを読んだりできます。

アクセス許可

初回は、ターミナルアプリが GroupShelf を制御してよいかを macOS が確認し、コマンドは応答を待ちます。許可しなかった場合は、システム設定 › プライバシーとセキュリティ › オートメーション で、ターミナルアプリの下にある 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 が表示されない場合は、Universal 版の代わりに VS Code の Apple silicon 版か Intel 版をインストールしてください。どちらにもこの項目があります。Homebrew の visual-studio-code cask なら、お使いの Mac のチップに合った版がインストールされます。

ウィンドウの指定

コマンドが <window> を受け取る箇所では、次の 3 通りの書き方ができます。空白を含むものは引用符で囲んでください。

同じアプリを 2 回書くと、そのアプリのウィンドウを 2 枚使います。

タイトルが複数のウィンドウに当てはまるとエラーになります。--frontmost を付けるとそのうち最前面のものを、--all を付けるとすべてを使います。--all は、タイトルなしで指定したアプリのウィンドウもすべて使います。

groupshelf はアプリを開かないため、アプリは起動しておく必要があります。group と add は、起動中のアプリのウィンドウが現れるのを最大 30 秒待つので、直前に開いたアプリでも使えます:

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

対象になるのは、このデスクトップにあるウィンドウ(最小化したものを含む)だけです。フルスクリーンのウィンドウは専用のデスクトップにあるため、対象になりません。

相対パスは現在のフォルダを基準に解釈されます。パスにタイトルを付けるときは、/Applications/Safari.app:Docs のように .app: の後に書きます。

コマンド

groupshelf help でコマンドの一覧を、groupshelf help <command> で各コマンドの説明を表示できます。GroupShelf が起動していなければ、コマンドがバックグラウンドで起動します。指定したアプリを開くことはありません。

オプションは -- より前ならどこに書いてもよく、値は空白か = の後に続けます(--name Work または --name=Work)。- で始まる名前のアプリは -- の後に書きます。

group

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

ウィンドウを、指定した順に 1 組のタブにまとめます。最初のウィンドウがグループの位置とサイズを決め、完了するとそのタブが表示されます。ほかのグループに入っているウィンドウは、そのグループを離れてこちらに加わります。

ウィンドウは 2 枚以上必要です(--all なら <window> は 1 つで足ります)。30 秒以内に現れないウィンドウがあれば、残りでグループを作り、見つからなかったものを報告します。まったく同じウィンドウからなるグループに対して実行すると、タブを指定の順に並べ替えるだけです。

オプション
--name <name>
新しいグループに名前を付けます。あとで --group で指定できます。
--frontmost
タイトルが複数のウィンドウに当てはまるとき、最前面のものを使います。
--all
当てはまるウィンドウをすべて使います。アプリならそのすべてのウィンドウ、タイトルならそれを含むすべてのウィンドウです。
使用例
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 で指定するか、そのグループのウィンドウの 1 つ(<member>、<window> と同じ書き方)で指定します。アプリや、--frontmost 付きのタイトルは、グループにまだないウィンドウがあればそれを使います。すでにグループにあるウィンドウはそのままです。

オプション
--group <name>
グループの名前(大文字・小文字は問いません)。--name か、タブバーを右クリックして「グループ名を付ける…」で付けた名前です。
--frontmost
タイトルが複数のウィンドウに当てはまるとき、最前面のものを使います。
--all
当てはまるウィンドウをすべて使います。アプリならそのすべてのウィンドウ、タイトルならそれを含むすべてのウィンドウです。
使用例
groupshelf add --group Work Slackgroupshelf add Code:proj-a Terminal:proj-a

detach

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

ウィンドウをグループから外します。1 枚だけになったグループは解除されます。アプリを開いたり待ったりはしないので、ウィンドウはすでにこのデスクトップにある必要があります。グループに入っていないウィンドウはそのままです。

オプション
--frontmost
タイトルが複数のウィンドウに当てはまるとき、最前面のものを使います。
--all
当てはまるウィンドウをすべて使います。アプリならそのすべてのウィンドウ、タイトルならそれを含むすべてのウィンドウです。
使用例
groupshelf detach Slack

ungroup

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

グループを解除します。ウィンドウはその場に残ります。グループは --group で指定するか(複数なら繰り返します)、そのグループのウィンドウの 1 つ(<member>、<window> と同じ書き方)で指定します。グループに入っていないウィンドウは飛ばします。見つからないものが 1 つでもあれば、どのグループも解除しません。

オプション
--group <name>
グループの名前(大文字・小文字は問いません)。--name か、タブバーを右クリックして「グループ名を付ける…」で付けた名前です。
使用例
groupshelf ungroup --group Workgroupshelf ungroup Code:proj-a

list

groupshelf list

このデスクトップにあるグループ化できるウィンドウを、手前から順に、最小化したものは最後に一覧表示します。GroupShelf 自身のウィンドウと、除外したアプリのウィンドウは含みません。1 行が 1 枚のウィンドウで、次の項目がタブ区切りで並びます(見出し行はありません):

  1. ウィンドウ ID
  2. アプリ名
  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 がエラーを返しました。起動していないアプリなど、指示の内容を直す必要があります。一部のウィンドウが欠けたままグループを作った場合も含みます。
2
使い方の誤り。コマンドラインそのものが間違っています。何が違うかと使い方を表示し、GroupShelf には接続しません。
3
GroupShelf に接続できませんでした。アクセス許可がないなど、環境のほうを直す必要があります。

トラブルシューティング

メッセージごとの意味と対処です。メッセージ中の名前や数字は例で、実際には入力した内容が表示されます。

GroupShelf への接続 · 終了ステータス 3

groupshelf: GroupShelf.app not found

コマンドが、付属元の GroupShelf を見つけられません。アプリの外にコピーしたコマンドで、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

ターミナルアプリに GroupShelf の制御が許可されていません。システム設定 › プライバシーとセキュリティ › オートメーション で、ターミナルアプリの下にある 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 が指示を届けられませんでした。数字は 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 は指示を 1 つずつ処理し、group と add はウィンドウを最大 30 秒待つことがあります。先の指示が終わってから、もう一度実行してください。

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

そのアプリは、設定 › グループ化 の「除外するアプリ」に入っています。グループにするには、そこから外してください。

ウィンドウの指定 · 終了ステータス 1

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

先にアプリを開いてください。そうすれば group と add は、そのウィンドウを最大 30 秒待ちます。

groupshelf: no application named "Safary"

つづりを確認してください。起動しておらず「アプリケーション」フォルダにもないアプリは、バンドル ID かパスでしか指定できません。

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

パスの先がアプリではありません。.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

2 つの引数が同じウィンドウを指しています。どちらかを削除してください。

groupshelf: GroupShelf can't group its own windows

コマンドから GroupShelf を外してください。

グループの指定 · 終了ステータス 1

groupshelf: no group named "Work"

その名前のグループはありません。groupshelf list の 5 番目の項目に、各ウィンドウのグループ名が表示されます。

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

同じ名前のグループが複数あります。代わりに、そのグループのウィンドウの 1 つを <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

ウィンドウが 2 枚そろわなかったため、何も変更していません。

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.

コマンドラインそのものが間違っています。1 行目が何が違うかを示し、続いてコマンドの使い方が表示されます。GroupShelf には何も送っていません。

← ホームへ戻る