Linha de comando

O comando groupshelf agrupa as janelas abertas, adiciona a grupos ou os desfaz e lista janelas, pelo Terminal ou por um script. Ele vem com o GroupShelf 1.3.0 e posteriores.

Instalação

O comando faz parte do GroupShelf.app. Instalá-lo significa criar um link para ele em uma pasta do seu PATH.

Com o Homebrew, ao instalar o GroupShelf o comando é vinculado automaticamente:

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

Se você instalou o GroupShelf com o Homebrew antes da 1.3.0, as atualizações feitas pelo app não adicionam o link. Execute isto uma vez:

brew reinstall --cask groupshelf

Sem o Homebrew, o GroupShelf mostra em Ajustes › Linha de Comando o comando que cria o link, pronto para copiar. Execute-o no Terminal; a senha do Mac será solicitada. Para o GroupShelf na pasta Aplicativos, ele é:

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

Os Ajustes só oferecem o comando quando o GroupShelf está na pasta Aplicativos e foi aberto de lá: um link para uma cópia em Downloads deixaria de funcionar ao mover o app.

Com o comando instalado, Ajustes › Linha de Comando mostra onde ele está, e groupshelf version exibe a versão do GroupShelf a que ele pertence.

Ativação

Os comandos que atuam sobre janelas só funcionam depois que você os permite: em Ajustes › Linha de Comando do GroupShelf, ative “Permitir controle pela linha de comando e por scripts”. A opção fica desativada até você ativá-la. help e version funcionam de qualquer forma.

Enquanto estiver ativado, os apps que você permitir controlar o GroupShelf (como o app de terminal) e tudo o que for executado neles poderão agrupar janelas e ler o título de cada janela desta mesa.

Permissões

Na primeira vez, o macOS pergunta se o seu app de terminal pode controlar o GroupShelf, e o comando aguarda a resposta. Se você recusou, ative o GroupShelf sob o app de terminal em Ajustes do Sistema › Privacidade e Segurança › Automação.

Visual Studio Code

A versão Universal do VS Code, a que a maioria das pessoas baixa (versões 1.104 e posteriores), não tem uma entrada que o macOS exige antes de pedir essa permissão. O macOS recusaria sem perguntar e nunca listaria o GroupShelf sob o Visual Studio Code, então o groupshelf faz o macOS perguntar mesmo assim. Ele exibe esta linha, e a caixa de diálogo cita o Visual Studio Code:

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

Responda uma vez e passa a funcionar dali em diante. Se o GroupShelf ainda não aparecer sob o Visual Studio Code em Automação, instale a versão Apple silicon ou Intel do VS Code em vez da Universal: ambas têm a entrada. O cask visual-studio-code do Homebrew instala a versão para o chip do seu Mac.

Como indicar janelas

Onde um comando aceitar um <window>, escreva-o de uma destas três formas. Coloque entre aspas tudo o que tiver espaços.

Escreva um app duas vezes para usar duas janelas dele.

Um título que corresponde a várias janelas é um erro, a menos que você adicione --frontmost, que usa a que está mais à frente, ou --all, que usa todas. --all também usa todas as janelas de um app indicado sem título.

O groupshelf nunca abre um app, então o app precisa estar aberto. group e add esperam até 30 segundos que uma janela de um app aberto apareça, então um app aberto logo antes funciona:

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

Só contam as janelas desta mesa, incluindo as minimizadas. Uma janela em tela cheia tem a própria mesa, então não conta.

Um caminho relativo é lido a partir da pasta atual. Para adicionar um título a um caminho, coloque-o depois de .app:, como em /Applications/Safari.app:Docs.

Comandos

groupshelf help lista os comandos e groupshelf help <command> explica um deles. Se o GroupShelf não estiver aberto, um comando o abre em segundo plano; ele nunca abre os apps que você indicar.

As opções podem ficar em qualquer lugar antes de um --, com o valor depois de um espaço ou de =: --name Work ou --name=Work. Coloque um app cujo nome comece com - depois de --.

group

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

Agrupa janelas em um único conjunto de abas, na ordem indicada. A primeira janela define a posição e o tamanho do grupo, e a aba dela é exibida ao final. Uma janela que já está em outro grupo sai dele para entrar neste.

São necessárias pelo menos duas janelas, ou um único <window> com --all. Se alguma não aparecer em 30 segundos, o grupo é formado com as demais e o comando informa as que faltaram. Executado em um grupo formado exatamente por essas janelas, ele apenas põe as abas na ordem indicada.

Opções
--name <name>
Dá um nome ao novo grupo, para encontrá-lo depois com --group.
--frontmost
Quando um título corresponde a várias janelas, usa a que está mais à frente.
--all
Usa todas as janelas que correspondem: todas as janelas de um app, todas as que têm um título.
Exemplos
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>...

Adiciona janelas ao fim de um grupo existente desta mesa, que mantém a posição, o tamanho e a aba exibida. Uma janela que já está em outro grupo é movida. Como em group, só são usadas janelas já abertas, com espera de até 30 segundos.

Indique o grupo com --group ou por uma das janelas dele (<member>, escrito como um <window>). Um app, ou um título com --frontmost, usa uma janela que o grupo ainda não tem, se houver; uma janela que já está no grupo fica como está.

Opções
--group <name>
Um grupo pelo nome, sem diferenciar maiúsculas: o dado com --name ou com “Nomear Grupo…” ao clicar com o botão direito na Barra de Abas dele.
--frontmost
Quando um título corresponde a várias janelas, usa a que está mais à frente.
--all
Usa todas as janelas que correspondem: todas as janelas de um app, todas as que têm um título.
Exemplos
groupshelf add --group Work Slackgroupshelf add Code:proj-a Terminal:proj-a

detach

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

Separa janelas dos seus grupos; um grupo que fica com uma só janela é desfeito. Nada é aberto nem aguardado: as janelas precisam já estar nesta mesa. Uma janela que não está em nenhum grupo fica como está.

Opções
--frontmost
Quando um título corresponde a várias janelas, usa a que está mais à frente.
--all
Usa todas as janelas que correspondem: todas as janelas de um app, todas as que têm um título.
Exemplo
groupshelf detach Slack

ungroup

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

Desfaz grupos, deixando as janelas onde estão. Indique um grupo com --group (repita para mais) ou por uma das janelas dele (<member>, escrito como um <window>). Uma janela que não está em nenhum grupo é ignorada. Se algum não for encontrado, nenhum grupo é desfeito.

Opções
--group <name>
Um grupo pelo nome, sem diferenciar maiúsculas: o dado com --name ou com “Nomear Grupo…” ao clicar com o botão direito na Barra de Abas dele.
Exemplos
groupshelf ungroup --group Workgroupshelf ungroup Code:proj-a

list

groupshelf list

Lista as janelas desta mesa que podem ser agrupadas, da frente para trás, com as minimizadas por último. As janelas do próprio GroupShelf e as de apps excluídos ficam de fora. Cada linha é uma janela, com estes campos separados por tabulações e sem linha de cabeçalho:

  1. ID de janela
  2. Nome do app
  3. Título
  4. Número do grupo, ou vazio
  5. Nome do grupo, ou vazio
  6. minimized, ou vazio
groupshelf list4211	Safari	GroupShelf — Command line	1	Work	4198	Terminal	proj-a — zsh	1	Work	4305	Mail	Inbox			3977	Notes	Shopping			minimized

Uma tabulação ou quebra de linha em um título vira um espaço, então os campos sempre se alinham. O ID funciona como <window> nos outros comandos; com o fzf, você pode escolher janelas e agrupá-las:

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

help

groupshelf help [<command>]

Mostra a lista de comandos ou o uso de um deles: group, add, detach, ungroup ou list.

Exemplo
groupshelf help group

version

groupshelf version

Mostra a versão e o build do GroupShelf que acompanha o comando. Os dois são sempre o mesmo build.

Código de saída

Os scripts podem agir conforme o código de saída. As mensagens vão para a saída de erro padrão e sempre começam com groupshelf:.

0
Sucesso.
1
O GroupShelf informou um erro: o pedido precisa ser corrigido, como um app que não está aberto. Um grupo formado sem algumas das janelas também conta.
2
Erro de uso: a própria linha de comando está errada. O comando diz o que está errado e mostra o uso, sem contatar o GroupShelf.
3
Não foi possível contatar o GroupShelf: a configuração precisa ser corrigida, como uma permissão que falta.

Solução de problemas

O que cada mensagem significa e o que fazer. Os nomes e números nelas são exemplos: os seus mostram o que você digitou.

Contatar o GroupShelf · Código de saída 3

groupshelf: GroupShelf.app not found

O comando não encontra o GroupShelf com que veio: é uma cópia guardada fora do app, e não há nenhum GroupShelf instalado. Instale o GroupShelf e crie o link do comando como em “Instalação”, em vez de copiá-lo.

groupshelf: GroupShelf could not be launched: <reason>

O GroupShelf não estava aberto, e o macOS não conseguiu abri-lo, pelo motivo indicado. Abra o GroupShelf você mesmo e execute o comando de novo.

groupshelf: GroupShelf did not start within 15 seconds

O GroupShelf foi aberto em segundo plano, mas não ficou pronto a tempo. Execute o comando de novo.

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

Na maioria das vezes, o macOS ainda está esperando a resposta ao pedido de permissão. Responda e execute o comando de novo.

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

O seu app de terminal não tem permissão para controlar o GroupShelf. Em Ajustes do Sistema › Privacidade e Segurança › Automação, ative o GroupShelf sob o 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

No terminal do VS Code, esta linha vem depois da anterior. Consulte Visual Studio Code em “Permissões”.

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

O GroupShelf que o comando encontrou é anterior a ele, como uma cópia antiga em outro lugar do Mac. Atualize o GroupShelf para a 1.3.0 ou posterior e remova as cópias antigas.

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

O macOS não conseguiu entregar o pedido por outro motivo; o número é o código de erro dele. Encerre e abra o GroupShelf de novo e tente outra vez. Se continuar acontecendo, contate o suporte informando o número.

Ajustes e estado do GroupShelf · Código de saída 1

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

Ative a opção em Ajustes › Linha de Comando, como em “Ativação”.

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

Sem ela, o GroupShelf não consegue mover janelas. Ative o GroupShelf em Ajustes do Sistema › Privacidade e Segurança › Acessibilidade.

groupshelf: GroupShelf is paused while Stage Manager is on

O GroupShelf não funciona junto com o Organizador Visual. Desative o Organizador Visual nos Ajustes do Sistema e reinicie o GroupShelf.

groupshelf: GroupShelf hasn't finished starting; try again

Execute o comando de novo daqui a pouco.

groupshelf: another group request is still running

O GroupShelf atende um pedido por vez, e group e add podem esperar até 30 segundos pelas janelas. Execute de novo quando o outro terminar.

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

O app está em “Apps Excluídos” em Ajustes › Agrupamento. Remova-o de lá para agrupar as janelas dele.

Como indicar janelas · Código de saída 1

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

Abra o app primeiro. Depois, group e add esperam até 30 segundos pela janela dele.

groupshelf: no application named "Safary"

Confira a grafia. Um app que não está aberto nem em uma pasta Aplicativos só pode ser indicado pelo ID do bundle ou caminho.

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

O caminho leva a algo que não é um app. Faça-o apontar para o próprio .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

Os títulos de várias janelas contêm o texto. Restrinja de uma das formas que a mensagem indica.

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

A janela foi fechada, ou está em outra mesa ou em tela cheia. Execute groupshelf list para ver os IDs atuais.

groupshelf: no window for "Slack" on this desktop

detach, ungroup e um <member> consideram só as janelas que já estão nesta mesa, sem esperar. Confira se a janela está aberta aqui.

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

Dois argumentos apontam para a mesma janela. Remova um deles.

groupshelf: GroupShelf can't group its own windows

Tire o GroupShelf do comando.

Como indicar grupos · Código de saída 1

groupshelf: no group named "Work"

Nenhum grupo tem esse nome. groupshelf list mostra o nome do grupo de cada janela no quinto campo.

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

Vários grupos têm esse nome. Indique o grupo por uma das janelas dele, como <member>.

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

add só adiciona a um grupo desta mesa. Vá para a mesa do grupo e execute o comando lá.

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

A janela indicada como <member> não está em nenhum grupo. Crie um com group.

Resultados parciais · Código de saída 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

Tudo antes do primeiro ponto e vírgula foi feito. Faltam as janelas citadas depois: nenhuma apareceu nesta mesa em 30 segundos.

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

Apareceram menos de duas janelas, então nada foi alterado.

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

O grupo da janela, ou o grupo em que ela entraria, está bloqueado. Clique com o botão direito na Barra de Abas do grupo bloqueado, escolha “Desbloquear Grupo” e execute o comando de novo.

Erros de uso · Código de saída 2

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

A própria linha de comando está errada: a primeira linha diz o quê, e em seguida vem o uso do comando. Nada foi enviado ao GroupShelf.

← Voltar ao início