Ligne de commande

La commande groupshelf groupe les fenêtres ouvertes, complète et défait des groupes, et liste les fenêtres, depuis Terminal ou un script. Elle est fournie avec GroupShelf 1.3.0 et versions ultérieures.

Installation

La commande fait partie de GroupShelf.app. L’installer consiste à la lier dans un dossier de votre PATH.

Avec Homebrew, installer GroupShelf lie la commande automatiquement :

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

Si vous avez installé GroupShelf avec Homebrew avant la version 1.3.0, les mises à jour faites depuis l’app n’ajoutent pas le lien. Exécutez ceci une fois :

brew reinstall --cask groupshelf

Sans Homebrew, GroupShelf affiche dans Réglages › Ligne de commande la commande qui crée le lien, prête à copier. Exécutez-la dans Terminal ; le mot de passe de votre Mac vous sera demandé. Pour GroupShelf dans le dossier Applications, la voici :

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

Les réglages ne la proposent qu’une fois GroupShelf placé dans le dossier Applications et ouvert depuis celui-ci : un lien vers une copie dans Téléchargements serait rompu dès que l’app serait déplacée.

Une fois la commande en place, Réglages › Ligne de commande indique où elle est installée, et groupshelf version affiche la version du GroupShelf auquel elle appartient.

Activation

Les commandes qui agissent sur les fenêtres ne fonctionnent qu’une fois autorisées : dans Réglages › Ligne de commande de GroupShelf, activez « Autoriser le contrôle depuis la ligne de commande et les scripts ». L’option reste désactivée tant que vous ne l’activez pas. help et version fonctionnent dans tous les cas.

Tant que l’option est activée, les apps que vous autorisez à contrôler GroupShelf (comme votre app de terminal) et tout ce qui s’y exécute peuvent grouper des fenêtres et lire le titre de chaque fenêtre de ce bureau.

Autorisations

La première fois, macOS demande si votre app de terminal peut contrôler GroupShelf, et la commande attend votre réponse. Si vous avez refusé, activez GroupShelf sous votre app de terminal dans Réglages Système › Confidentialité et sécurité › Automatisation.

Visual Studio Code

La version Universal de VS Code, celle que la plupart des gens téléchargent (versions 1.104 et ultérieures), n’a pas une entrée que macOS exige avant de demander cette autorisation. macOS refuserait sans demander et n’afficherait jamais GroupShelf sous Visual Studio Code ; groupshelf amène donc macOS à demander malgré tout. Il affiche cette ligne, et la boîte de dialogue nomme Visual Studio Code :

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

Répondez-y une fois et tout fonctionne ensuite. Si GroupShelf n’apparaît toujours pas sous Visual Studio Code dans Automatisation, installez la version Apple silicon ou Intel de VS Code au lieu d’Universal : toutes deux contiennent l’entrée. Le cask Homebrew visual-studio-code installe la version adaptée à la puce de votre Mac.

Désigner des fenêtres

Partout où une commande attend un <window>, écrivez-le de l’une des trois façons suivantes. Mettez entre guillemets tout ce qui contient des espaces.

Nommez une app deux fois pour prendre deux de ses fenêtres.

Un titre qui correspond à plusieurs fenêtres est une erreur, sauf si vous ajoutez --frontmost, qui prend la plus en avant, ou --all, qui les prend toutes. --all prend aussi toutes les fenêtres d’une app nommée sans titre.

groupshelf n’ouvre jamais d’app : l’app doit donc être ouverte. group et add attendent jusqu’à 30 secondes qu’une fenêtre d’une app ouverte apparaisse ; une app ouverte juste avant fonctionne donc :

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

Seules comptent les fenêtres de ce bureau, y compris les fenêtres minimisées. Une fenêtre en plein écran a son propre bureau : elle ne compte donc pas.

Un chemin relatif part du dossier actuel. Pour ajouter un titre à un chemin, placez-le après .app:, comme dans /Applications/Safari.app:Docs.

Commandes

groupshelf help liste les commandes et groupshelf help <command> en explique une. Si GroupShelf n’est pas ouvert, une commande le lance en arrière-plan ; elle n’ouvre jamais les apps que vous indiquez.

Les options peuvent figurer n’importe où avant un --, leur valeur suivant une espace ou un = : --name Work ou --name=Work. Placez une app dont le nom commence par - après --.

group

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

Groupe des fenêtres en un seul ensemble d’onglets, dans l’ordre indiqué. La première fenêtre fixe la position et la taille du groupe, et son onglet est affiché à la fin. Une fenêtre déjà dans un autre groupe le quitte pour celui-ci.

Il faut au moins deux fenêtres, ou un seul <window> avec --all. Si certaines n’apparaissent pas dans les 30 secondes, le groupe est formé avec les autres et la commande signale celles qui manquent. Lancée sur un groupe composé exactement de ces fenêtres, elle se contente de remettre les onglets dans l’ordre indiqué.

Options
--name <name>
Nomme le nouveau groupe, pour le retrouver ensuite avec --group.
--frontmost
Prend la plus en avant quand un titre correspond à plusieurs fenêtres.
--all
Prend toutes les fenêtres qui correspondent : toutes celles d’une app, toutes celles qui portent un titre.
Exemples
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>...

Ajoute des fenêtres à la fin d’un groupe existant de ce bureau, qui garde sa position, sa taille et son onglet affiché. Une fenêtre déjà dans un autre groupe est déplacée. Comme avec group, seules les fenêtres déjà ouvertes sont utilisées, avec une attente de 30 secondes au plus.

Désignez le groupe avec --group, ou par l’une de ses fenêtres (<member>, écrit comme un <window>). Une app, ou un titre avec --frontmost, prend une fenêtre que le groupe n’a pas encore s’il y en a une ; une fenêtre déjà dans le groupe reste telle quelle.

Options
--group <name>
Un groupe désigné par son nom, sans tenir compte des majuscules : celui donné avec --name, ou avec « Nommer le groupe… » en cliquant sur sa barre d’onglets avec le bouton droit.
--frontmost
Prend la plus en avant quand un titre correspond à plusieurs fenêtres.
--all
Prend toutes les fenêtres qui correspondent : toutes celles d’une app, toutes celles qui portent un titre.
Exemples
groupshelf add --group Work Slackgroupshelf add Code:proj-a Terminal:proj-a

detach

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

Détache des fenêtres de leurs groupes ; un groupe qui n’a plus qu’une fenêtre est dissous. Rien n’est ouvert ni attendu : les fenêtres doivent déjà être sur ce bureau. Une fenêtre qui n’est dans aucun groupe reste telle quelle.

Options
--frontmost
Prend la plus en avant quand un titre correspond à plusieurs fenêtres.
--all
Prend toutes les fenêtres qui correspondent : toutes celles d’une app, toutes celles qui portent un titre.
Exemple
groupshelf detach Slack

ungroup

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

Dissout des groupes, en laissant leurs fenêtres en place. Désignez un groupe avec --group (à répéter pour en dissoudre plusieurs), ou par l’une de ses fenêtres (<member>, écrit comme un <window>). Une fenêtre qui n’est dans aucun groupe est ignorée. Si l’un d’eux est introuvable, aucun groupe n’est dissous.

Options
--group <name>
Un groupe désigné par son nom, sans tenir compte des majuscules : celui donné avec --name, ou avec « Nommer le groupe… » en cliquant sur sa barre d’onglets avec le bouton droit.
Exemples
groupshelf ungroup --group Workgroupshelf ungroup Code:proj-a

list

groupshelf list

Liste les fenêtres de ce bureau qui peuvent être groupées, de l’avant vers l’arrière, les fenêtres minimisées en dernier. Les fenêtres de GroupShelf et celles des apps exclues n’y figurent pas. Chaque ligne correspond à une fenêtre, avec ces champs séparés par des tabulations et sans ligne d’en-tête :

  1. ID de fenêtre
  2. Nom de l’app
  3. Titre
  4. Numéro du groupe, ou vide
  5. Nom du groupe, ou vide
  6. minimized, ou vide
groupshelf list4211	Safari	GroupShelf — Command line	1	Work	4198	Terminal	proj-a — zsh	1	Work	4305	Mail	Inbox			3977	Notes	Shopping			minimized

Une tabulation ou un saut de ligne dans un titre devient une espace, pour que les champs restent alignés. L’ID sert de <window> aux autres commandes ; avec fzf, vous pouvez choisir des fenêtres et les grouper :

Exemple
groupshelf list | fzf -m | cut -f1 | xargs groupshelf group

help

groupshelf help [<command>]

Affiche la liste des commandes, ou l’utilisation de l’une d’elles : group, add, detach, ungroup ou list.

Exemple
groupshelf help group

version

groupshelf version

Affiche la version et le build du GroupShelf fourni avec la commande. Les deux forment toujours un seul et même build.

Code de sortie

Les scripts peuvent agir selon le code de sortie. Les messages vont sur la sortie d’erreur standard et commencent tous par groupshelf:.

0
Succès.
1
GroupShelf a signalé une erreur : la requête est à corriger, par exemple une app qui n’est pas ouverte. Un groupe formé sans certaines de ses fenêtres compte aussi.
2
Erreur d’utilisation : la ligne de commande elle-même est incorrecte. La commande indique le problème et affiche son utilisation, sans contacter GroupShelf.
3
GroupShelf est injoignable : la configuration est à corriger, par exemple une autorisation manquante.

Dépannage

Ce que signifie chaque message, et que faire. Les noms et nombres qu’ils contiennent sont des exemples : les vôtres reprennent ce que vous avez saisi.

Joindre GroupShelf · Code de sortie 3

groupshelf: GroupShelf.app not found

La commande ne trouve pas le GroupShelf avec lequel elle est fournie : c’est une copie conservée hors de l’app, et aucun GroupShelf n’est installé. Installez GroupShelf, puis liez la commande comme indiqué dans « Installation » au lieu de la copier.

groupshelf: GroupShelf could not be launched: <reason>

GroupShelf n’était pas ouvert, et macOS n’a pas pu l’ouvrir, pour la raison indiquée. Ouvrez GroupShelf vous-même, puis relancez la commande.

groupshelf: GroupShelf did not start within 15 seconds

GroupShelf a été ouvert en arrière-plan, mais n’était pas prêt à temps. Relancez la commande.

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

Le plus souvent, macOS attend encore votre réponse à sa demande d’autorisation. Répondez-y, puis relancez la commande.

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

Votre app de terminal n’est pas autorisée à contrôler GroupShelf. Dans Réglages Système › Confidentialité et sécurité › Automatisation, activez GroupShelf sous votre app de terminal.

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

Dans le terminal de VS Code, cette ligne suit la précédente. Voir Visual Studio Code dans « Autorisations ».

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

Le GroupShelf joint par la commande lui est antérieur, par exemple une ancienne copie ailleurs sur votre Mac. Mettez GroupShelf à jour vers la version 1.3.0 ou ultérieure, et supprimez les anciennes copies.

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

macOS n’a pas pu transmettre la requête pour une autre raison ; le nombre est son code d’erreur. Quittez GroupShelf, rouvrez-le, puis réessayez. Si cela se reproduit, contactez l’assistance en indiquant ce nombre.

Réglages et état de GroupShelf · Code de sortie 1

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

Activez l’option dans Réglages › Ligne de commande, comme indiqué dans « Activation ».

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

Sans elle, GroupShelf ne peut pas déplacer de fenêtres. Activez GroupShelf dans Réglages Système › Confidentialité et sécurité › Accessibilité.

groupshelf: GroupShelf is paused while Stage Manager is on

GroupShelf ne peut pas fonctionner avec Stage Manager. Désactivez Stage Manager dans Réglages Système, puis redémarrez GroupShelf.

groupshelf: GroupShelf hasn't finished starting; try again

Relancez la commande dans un instant.

groupshelf: another group request is still running

GroupShelf traite une requête à la fois, et group et add peuvent attendre des fenêtres jusqu’à 30 secondes. Relancez la commande une fois l’autre terminée.

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

L’app figure dans « Apps exclues » sous Réglages › Regroupement. Retirez-la de cette liste pour grouper ses fenêtres.

Désigner des fenêtres · Code de sortie 1

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

Ouvrez d’abord l’app. group et add attendent ensuite sa fenêtre jusqu’à 30 secondes.

groupshelf: no application named "Safary"

Vérifiez l’orthographe. Une app qui n’est pas ouverte et ne se trouve pas dans un dossier Applications ne peut être désignée que par son identifiant de bundle ou son chemin.

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

Le chemin mène à autre chose qu’une app. Faites-le pointer sur le .app lui-même.

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

Le titre de plusieurs fenêtres contient le texte. Affinez avec l’un des moyens que le message indique.

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

La fenêtre a été fermée, ou elle est sur un autre bureau ou en plein écran. Lancez groupshelf list pour obtenir les ID actuels.

groupshelf: no window for "Slack" on this desktop

detach, ungroup et un <member> s’en tiennent aux fenêtres déjà présentes sur ce bureau, sans attendre. Vérifiez que la fenêtre est ouverte ici.

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

Deux arguments désignent la même fenêtre. Retirez-en un.

groupshelf: GroupShelf can't group its own windows

Retirez GroupShelf de la commande.

Désigner des groupes · Code de sortie 1

groupshelf: no group named "Work"

Aucun groupe ne porte ce nom. groupshelf list indique le nom du groupe de chaque fenêtre dans son cinquième champ.

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

Plusieurs groupes portent ce nom. Désignez plutôt le groupe par l’une de ses fenêtres, en tant que <member>.

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

add n’ajoute qu’à un groupe de ce bureau. Allez sur le bureau du groupe et lancez la commande depuis celui-ci.

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

La fenêtre donnée comme <member> n’est dans aucun groupe. Créez-en un avec group.

Résultats partiels · Code de sortie 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

Tout ce qui précède le premier point-virgule a été fait. Les fenêtres citées après manquent : aucune n’est apparue sur ce bureau dans les 30 secondes.

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

Moins de deux fenêtres ont été trouvées : rien n’a été modifié.

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

Le groupe de la fenêtre, ou celui qu’elle rejoindrait, est verrouillé. Cliquez avec le bouton droit sur la barre d’onglets du groupe verrouillé, choisissez « Déverrouiller le groupe », puis relancez la commande.

Erreurs d’utilisation · Code de sortie 2

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

La ligne de commande elle-même est incorrecte : la première ligne indique le problème, suivie de l’utilisation de la commande. Rien n’a été envoyé à GroupShelf.

← Retour à l’accueil