Línea de comandos

El comando groupshelf agrupa las ventanas abiertas, añade a grupos o los deshace y lista ventanas, desde Terminal o un script. Viene con GroupShelf 1.3.0 y posteriores.

Instalación

El comando forma parte de GroupShelf.app. Instalarlo consiste en enlazarlo en una carpeta de tu PATH.

Con Homebrew, al instalar GroupShelf el comando se enlaza automáticamente:

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

Si instalaste GroupShelf con Homebrew antes de la 1.3.0, las actualizaciones desde la app no añaden el enlace. Ejecuta esto una vez:

$ brew reinstall --cask groupshelf

Sin Homebrew, GroupShelf muestra en Ajustes › Línea de comandos el comando que crea el enlace, listo para copiar. Ejecútalo en Terminal; se te pedirá la contraseña del Mac. Para GroupShelf en la carpeta Aplicaciones, es este:

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

Los ajustes solo lo ofrecen cuando GroupShelf está en la carpeta Aplicaciones y se ha abierto desde allí: un enlace a una copia en Descargas dejaría de funcionar al mover la app.

Con el comando instalado, Ajustes › Línea de comandos muestra dónde está, y groupshelf version indica la versión del GroupShelf al que pertenece.

Activación

Los comandos que actúan sobre ventanas solo funcionan cuando los permites: en Ajustes › Línea de comandos de GroupShelf, activa “Permitir el control desde la línea de comandos y scripts”. Sigue desactivado hasta que lo actives. help y version funcionan en cualquier caso.

Mientras está activado, las apps a las que permitas controlar GroupShelf (como tu app de terminal) y todo lo que se ejecute en ellas pueden agrupar ventanas y leer el título de cada ventana de este escritorio.

Permisos

La primera vez, macOS pregunta si tu app de terminal puede controlar GroupShelf, y el comando espera tu respuesta. Si lo rechazaste, activa GroupShelf bajo tu app de terminal en Ajustes del Sistema › Privacidad y seguridad › Automatización.

Visual Studio Code

La versión Universal de VS Code, la que descarga la mayoría (versiones 1.104 y posteriores), carece de una entrada que macOS necesita antes de pedir este permiso. macOS lo denegaría sin preguntar y nunca mostraría GroupShelf bajo Visual Studio Code, así que groupshelf consigue que macOS pregunte igualmente. Muestra esta línea, y el cuadro de diálogo nombra a Visual Studio Code:

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

Respóndelo una vez y funcionará a partir de entonces. Si GroupShelf sigue sin aparecer bajo Visual Studio Code en Automatización, instala la versión Apple silicon o Intel de VS Code en lugar de la Universal: ambas incluyen la entrada. El cask visual-studio-code de Homebrew instala la versión para el chip de tu Mac.

Cómo indicar ventanas

Donde un comando acepte un <window>, escríbelo de una de estas tres formas. Pon entre comillas todo lo que tenga espacios.

Una app
Una de sus ventanas: la activa en esa app o, si no, la que está más al frente. Indica la app con el nombre que muestra el Dock o con su nombre de archivo, en mayúsculas o minúsculas, o con su ID de bundle o su ruta.Safari"Visual Studio Code"com.apple.Safari/Applications/Safari.app
Una app y parte del título
Su ventana cuyo título contiene el texto, sin distinguir mayúsculas y minúsculas.Code:proj-a"Terminal:my server"
Un ID de ventana
Un número de groupshelf list.

Escribe una app dos veces para tomar dos de sus ventanas.

Un título que coincide con varias ventanas es un error, salvo que añadas --frontmost, que toma la que está más al frente, o --all, que las toma todas. --all también toma todas las ventanas de una app indicada sin título.

groupshelf nunca abre una app, así que la app debe estar abierta. group y add esperan hasta 30 segundos a que aparezca una ventana de una app abierta, de modo que una app abierta justo antes funciona:

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

Solo cuentan las ventanas de este escritorio, incluidas las minimizadas. Una ventana a pantalla completa tiene su propio escritorio, así que no cuenta.

Una ruta relativa se lee desde la carpeta actual. Para añadir un título a una ruta, ponlo después de .app:, como en /Applications/Safari.app:Docs.

Comandos

groupshelf help lista los comandos y groupshelf help <command> explica uno. Si GroupShelf no está abierto, un comando lo inicia en segundo plano; nunca abre las apps que indiques.

Las opciones pueden ir en cualquier lugar antes de un --, con su valor tras un espacio o un =: --name Work o --name=Work. Pon una app cuyo nombre empiece por - después de --.

group

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

Agrupa ventanas en un solo conjunto de pestañas, en el orden indicado. La primera ventana fija la posición y el tamaño del grupo, y su pestaña se muestra al terminar. Una ventana que ya está en otro grupo lo deja para unirse a este.

Necesita al menos dos ventanas, o un solo <window> con --all. Si alguna no aparece en 30 segundos, el grupo se forma con el resto y el comando indica las que faltan. Si se ejecuta sobre un grupo formado exactamente por esas ventanas, solo pone las pestañas en el orden indicado.

Opciones

--name <name>: Pone nombre al nuevo grupo, para encontrarlo después con --group.
--frontmost: Cuando un título coincide con varias ventanas, toma la que está más al frente.
--all: Toma todas las ventanas que coinciden: todas las de una app, todas las que llevan un título.

Ejemplos

$ groupshelf group Safari Terminal Notes Mail$ groupshelf group --name Work Code:proj-a Terminal:proj-a Safari$ open -a Safari && open -a Terminal && groupshelf group Safari Terminal$ groupshelf group --all Terminal

add

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

Añade ventanas al final de un grupo existente de este escritorio, que conserva su posición, su tamaño y la pestaña que muestra. Una ventana que ya está en otro grupo se mueve. Como con group, solo se usan ventanas ya abiertas, con una espera de hasta 30 segundos.

Indica el grupo con --group o con una de sus ventanas (<member>, escrito como un <window>). Una app, o un título con --frontmost, toma una ventana que el grupo aún no tenga, si la hay; una ventana que ya está en el grupo se queda como está.

Opciones

--group <name>: Un grupo por su nombre, sin distinguir mayúsculas: el que diste con --name o con “Nombrar grupo…” al hacer clic con el botón derecho en su barra de pestañas.
--frontmost: Cuando un título coincide con varias ventanas, toma la que está más al frente.
--all: Toma todas las ventanas que coinciden: todas las de una app, todas las que llevan un título.

Ejemplos

$ groupshelf add --group Work Slack$ groupshelf add Code:proj-a Terminal:proj-a

detach

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

Separa ventanas de sus grupos; un grupo que se queda con una sola ventana se disuelve. No se abre ni se espera nada: las ventanas deben estar ya en este escritorio. Una ventana que no está en ningún grupo se queda como está.

Opciones

--frontmost: Cuando un título coincide con varias ventanas, toma la que está más al frente.
--all: Toma todas las ventanas que coinciden: todas las de una app, todas las que llevan un título.

Ejemplo

$ groupshelf detach Slack

ungroup

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

Disuelve grupos y deja sus ventanas donde están. Indica un grupo con --group (repítelo para más) o con una de sus ventanas (<member>, escrito como un <window>). Una ventana que no está en ningún grupo se omite. Si alguno no se encuentra, no se disuelve ningún grupo.

Opciones

--group <name>: Un grupo por su nombre, sin distinguir mayúsculas: el que diste con --name o con “Nombrar grupo…” al hacer clic con el botón derecho en su barra de pestañas.

Ejemplos

$ groupshelf ungroup --group Work$ groupshelf ungroup Code:proj-a

list

groupshelf list

Lista las ventanas de este escritorio que se pueden agrupar, de delante hacia atrás, con las minimizadas al final. No incluye las ventanas de GroupShelf ni las de apps excluidas. Cada línea es una ventana, con estos campos separados por tabuladores y sin línea de encabezado:

ID de ventana
Nombre de la app
Título
Número del grupo, o vacío
Nombre del grupo, o vacío
minimized, o vacío

$ groupshelf list4211	Safari	GroupShelf — Command line	1	Work	4198	Terminal	proj-a — zsh	1	Work	4305	Mail	Inbox			3977	Notes	Shopping			minimized

Un tabulador o un salto de línea dentro de un título se convierte en un espacio, así que los campos siempre cuadran. El ID sirve como <window> para los demás comandos; con fzf puedes elegir ventanas y agruparlas:

Ejemplo

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

help

groupshelf help [<command>]

Muestra la lista de comandos o el uso de uno de ellos: group, add, detach, ungroup o list.

Ejemplo

$ groupshelf help group

version

groupshelf version

Muestra la versión y la compilación del GroupShelf con el que viene el comando. Ambos son siempre la misma compilación.

Código de salida

Los scripts pueden actuar según el código de salida. Los mensajes van a la salida de error estándar y empiezan siempre por groupshelf:.

0: Éxito.
1: GroupShelf informó de un error: hay que corregir la petición, por ejemplo una app que no está abierta. También cuenta un grupo formado sin algunas de sus ventanas.
2: Error de uso: la propia línea de comandos es incorrecta. El comando indica qué falla y muestra su uso, sin contactar con GroupShelf.
3: No se pudo contactar con GroupShelf: hay que corregir la configuración, por ejemplo un permiso que falta.

Solución de problemas

Qué significa cada mensaje y qué hacer. Los nombres y números que aparecen son ejemplos: los tuyos muestran lo que escribiste.

Contactar con GroupShelf · Código de salida 3

groupshelf: GroupShelf.app not found

El comando no encuentra el GroupShelf con el que vino: es una copia guardada fuera de la app y no hay ningún GroupShelf instalado. Instala GroupShelf y enlaza el comando como en “Instalación” en lugar de copiarlo.

groupshelf: GroupShelf could not be launched: <reason>

GroupShelf no estaba abierto y macOS no pudo abrirlo, por el motivo indicado. Abre GroupShelf tú mismo y vuelve a ejecutar el comando.

groupshelf: GroupShelf did not start within 15 seconds

GroupShelf se abrió en segundo plano, pero no estuvo listo a tiempo. Vuelve a ejecutar el comando.

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

Lo más habitual es que macOS siga esperando tu respuesta a su petición de permiso. Respóndela y vuelve a ejecutar el comando.

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

Tu app de terminal no tiene permiso para controlar GroupShelf. En Ajustes del Sistema › Privacidad y seguridad › Automatización, activa GroupShelf bajo tu 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

En el terminal de VS Code, esta línea sigue a la anterior. Consulta Visual Studio Code en “Permisos”.

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

El GroupShelf al que llegó el comando es anterior a él, por ejemplo una copia antigua en otro lugar del Mac. Actualiza GroupShelf a la 1.3.0 o posterior y elimina las copias antiguas.

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

macOS no pudo entregar la petición por otro motivo; el número es su código de error. Sal de GroupShelf, vuelve a abrirlo e inténtalo de nuevo. Si sigue ocurriendo, contacta con soporte indicando el número.

Ajustes y estado de GroupShelf · Código de salida 1

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

Activa el interruptor en Ajustes › Línea de comandos, como en “Activación”.

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

Sin él, GroupShelf no puede mover ventanas. Activa GroupShelf en Ajustes del Sistema › Privacidad y seguridad › Accesibilidad.

groupshelf: GroupShelf is paused while Stage Manager is on

GroupShelf no puede funcionar junto con Organizador visual. Desactiva Organizador visual en Ajustes del Sistema y reinicia GroupShelf.

groupshelf: GroupShelf hasn't finished starting; try again

Vuelve a ejecutar el comando dentro de un momento.

groupshelf: another group request is still running

GroupShelf atiende una petición cada vez, y group y add pueden esperar hasta 30 segundos a las ventanas. Vuelve a ejecutarlo cuando la otra termine.

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

La app está en “Apps excluidas” en Ajustes › Agrupación. Quítala de ahí para agrupar sus ventanas.

Cómo indicar ventanas · Código de salida 1

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

Abre primero la app. Después, group y add esperan hasta 30 segundos a su ventana.

groupshelf: no application named "Safary"

Revisa cómo está escrito. Una app que no está abierta ni en una carpeta Aplicaciones solo se puede indicar con su ID de bundle o su ruta.

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

La ruta lleva a algo que no es una app. Haz que apunte al propio .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

Los títulos de varias ventanas contienen el texto. Acótalo de una de las formas que indica el mensaje.

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

La ventana se ha cerrado o está en otro escritorio o a pantalla completa. Ejecuta groupshelf list para ver los ID actuales.

groupshelf: no window for "Slack" on this desktop

detach, ungroup y un <member> se fijan solo en las ventanas que ya están en este escritorio, sin esperar. Comprueba que la ventana está abierta aquí.

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

Dos argumentos apuntan a la misma ventana. Quita uno de ellos.

groupshelf: GroupShelf can't group its own windows

Quita GroupShelf del comando.

Cómo indicar grupos · Código de salida 1

groupshelf: no group named "Work"

Ningún grupo tiene ese nombre. groupshelf list muestra el nombre del grupo de cada ventana en su quinto campo.

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

Varios grupos comparten el nombre. Indica el grupo con una de sus ventanas, como <member>.

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

add solo añade a un grupo de este escritorio. Ve al escritorio del grupo y ejecútalo allí.

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

La ventana indicada como <member> no está en ningún grupo. Crea uno con group.

Resultados parciales · Código de salida 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

Todo lo anterior al primer punto y coma se ha hecho. Faltan las ventanas citadas después: ninguna apareció en este escritorio en 30 segundos.

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

Aparecieron menos de dos ventanas, así que no se cambió nada.

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

El grupo de la ventana, o el grupo al que se uniría, está bloqueado. Haz clic con el botón derecho en la barra de pestañas del grupo bloqueado, elige “Desbloquear grupo” y vuelve a ejecutar el comando.

Errores de uso · Código de salida 2

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

La propia línea de comandos es incorrecta: la primera línea dice qué falla y a continuación aparece el uso del comando. No se envió nada a GroupShelf.

← Volver al inicio