Documentación de automatización

Referencia de línea de comandos

Integra popCalendar con tu alternativa al Dock u otras herramientas para Mac. Abre calendarios, elige fechas, gestiona planes y exporta imágenes mediante la CLI.

Estas guías describen popCalendar 1.3 y versiones posteriores. Algunas acciones requieren una versión más reciente del sistema, como se indica a continuación.

Una experiencia de calendario completa para tu herramienta

Añade popCalendar a tu alternativa al Dock, lanzador de apps, utilidad de la barra de menús o cualquier otra herramienta para Mac. Ofrece una experiencia de calendario completa sin tener que implementarla tú mismo, utilizando ventanas de calendario nativas, ventanas emergentes ancladas y selección de fechas mediante la CLI.

Los desarrolladores pueden contactarnos para obtener un código promocional gratuito de popCalendar y ayuda práctica mientras crean una integración.

Escribe a support@apptrust.app

Cada herramienta que implemente una integración con popCalendar tendrá una sección dedicada en popcalendar.app como integración con soporte oficial. Avísanos cuando la tuya esté lista.

Volver al índice

Ejecuta desde el paquete de la app

Con popCalendar instalado, no hace falta un paquete CLI separado. Ejecuta el archivo principal con su ruta completa. Todos los comandos empiezan por --. Ejecutarlo sin un comando inicia la app normal.

"/Applications/popCalendar.app/Contents/MacOS/popCalendar" --help

Puedes añadir el directorio del ejecutable a PATH para la sesión actual de terminal. También puedes añadir esa línea a la configuración de tu shell. Usa la ubicación real de la app si la has movido o renombrado. El ejecutable de Setapp también se llama popCalendar. Usa una ruta completa para elegir la edición si tienes ambas instaladas.

export PATH="${PATH:+$PATH:}"'/Applications/popCalendar.app/Contents/MacOS'
popCalendar --help
Volver al índice

Mostrar un calendario en Terminal

Usa --terminal para mostrar el calendario sin abrir una ventana de calendario. Primero activa Calendarios en Terminal en Ajustes > Automatización y privacidad. Vista previa abre un diálogo de ejemplo con comandos que puedes copiar. Los calendarios básicos funcionan localmente. Los datos privados solicitados se leen a través de la app en segundo plano.

"/Applications/popCalendar.app/Contents/MacOS/popCalendar" --terminal
"/Applications/popCalendar.app/Contents/MacOS/popCalendar" --terminal --interactive
"/Applications/popCalendar.app/Contents/MacOS/popCalendar" --terminal --year 2027

Sin un diseño explícito, se muestra un año completo si cabe o un mes si no. El modo interactivo se adapta al cambiar el tamaño hasta que eliges un diseño o seleccionas un intervalo. Las tuberías, JSON y la salida de solo agenda usan un mes de forma predeterminada.

Volver al índice

Eventos, planes y días laborables

Usa --events para incluir eventos, --agenda para una lista de eventos, --plans para marcar planes guardados y --working-days para tu horario laboral. El filtro de conjunto de calendarios solo se aplica a ese comando y no cambia el conjunto activo. --search busca en títulos y ubicaciones. Concede acceso a los calendarios en la app antes de solicitar eventos.

popCalendar --terminal --events today --agenda
popCalendar --terminal --events week --calendar-set current
popCalendar --terminal --months 3 --plans all --working-days
popCalendar --terminal --events month --search meeting --limit 20
popCalendar --terminal --start 2027-03-01 --end 2027-03-14 --events range

La opción week abarca los siete días siguientes desde --date o desde hoy. Un intervalo incluye ambos extremos. Sin una selección explícita, los eventos de range abarcan los meses mostrados. Las fechas y los encabezados usan el calendario gregoriano.

Volver al índice

Navegar en modo interactivo

Usa las flechas o h/j/k/l para moverte entre días, n/p para periodos, m/y para mes o año y t para hoy. Pulsa v para marcar el inicio y el final de un intervalo, c para borrarlo, g para ir a una fecha, / para buscar y ? para obtener ayuda. Pulsa q o Escape para salir.

Alterna eventos con e, agenda con a, planes con b, días laborables con d y números de semana con w. Pulsa s para el siguiente conjunto de calendarios, r para actualizar y PageUp/PageDown o Space para desplazarte.

También funcionan los comandos con palabras completas, sin distinguir mayúsculas y minúsculas. En el modo de respuesta inmediata, pulsa primero la tecla de dos puntos, escribe un comando y pulsa Enter. Si el pie indica que debes usar Enter, escribe el comando directamente y pulsa Enter. Escape cancela primero una entrada activa antes de salir.

month  year  next  previous  today
left  right  up  down  range  clear
events  agenda  plans  working-days  sets  week-numbers
goto 2027-03-01
search meeting
refresh  page-up  page-down  home  end
help  quit  exit
Volver al índice

Opciones de salida de Terminal

Elige una fecha, un mes, un año, un modo o entre 1 y 24 meses. Indica --start y --end juntos, sin otra opción de fecha o modo. Usa --time-zone, --first-weekday y --week-numbers para configurar el calendario. --width acepta de 32 a 240 columnas, --limit de 1 a 500 eventos y --color acepta auto, always o never.

popCalendar --terminal --mode two-years --date 2027-01-01 --week-numbers
popCalendar --terminal --month 2027-03 --time-zone Europe/Kyiv --first-weekday monday
popCalendar --terminal --year 2027 --width 120 --color never > calendar.txt
popCalendar --terminal --events today --json > agenda.json

La salida redirigida es texto sin formato. --json devuelve datos estructurados sin formato ANSI y no se puede combinar con --interactive ni --color always. Los comandos de Terminal solo leen datos y no modifican eventos, planes ni conjuntos de calendarios.

Volver al índice

Abre y controla calendarios

Las opciones admiten --opción valor o --opción=valor. La sesión predeterminada es cli. Reutilizar una sesión actualiza la misma ventana. Usa nombres distintos para ventanas independientes. Se admiten los seis modos.

popCalendar --open --session work --mode two-years --date 2027-01-01
popCalendar --popup --session picker --mode month --anchor 400,850,40,24 --size 520x720
popCalendar --update --session picker --date 2027-03-01
popCalendar --move --session picker --anchor 600,850,40,24
popCalendar --close --session picker

Para una vista superpuesta a pantalla completa, usa --presentation fullscreen con --display current, main o el UUID de una pantalla. Ocupa una pantalla sin crear un espacio de macOS. Escape o volver a alternar la misma sesión la cierra. Estas sesiones rechazan las opciones de tamaño, posición, anclaje, flecha y coordenadas. Cierra la sesión antes de cambiar su presentación.

popCalendar --toggle --session overview --presentation fullscreen --mode two-years --display current
Volver al índice

Devuelve una selección confirmada

--select abre un selector y espera la confirmación. El tiempo de espera predeterminado es de 300 segundos. Configura --timeout entre 1 y 86400. Escape, cerrar el selector o Control-C lo cancelan. Se devuelven hasta 128 intervalos separados del último panel utilizado. Sin --json, cada línea contiene START END. Se incluyen ambas fechas.

popCalendar --select --session picker --mode month --date 2027-03-01 --json --timeout 300
{"version":1,"status":"selected","session":"picker","timeZone":"America/Los_Angeles","ranges":[{"start":"2027-03-01","end":"2027-03-07"}]}
Volver al índice

Planes, días laborables e imágenes

Sustituye SET_UUID y PLAN_UUID por los identificadores que devuelven --sets y --plans. Usa UUID distintos para REQUEST_UUID y NEW_REQUEST_UUID. Los permisos necesarios se describen en la introducción a la automatización.

Comando u opciónQué hace
--helpMuestra la referencia completa de comandos y opciones.
--versionMuestra la versión y la compilación de la app.
--capabilities [--json]Devuelve los comandos y límites admitidos sin abrir la app.
--doctor [--json] [--timeout SECONDS]Comprueba la identidad de la app, los permisos y la comunicación con ella.
--sets [--json]Devuelve nombres e identificadores de conjuntos guardados.
--sessions [--json]Devuelve los identificadores de sesiones de integración abiertas en Mac.
--plans [--name SEARCH] [--id UUID] [--json]Devuelve planes guardados, sus intervalos e información de repetición. Filtra por nombre o identificador.
--create-plan --name NAME --start YYYY-MM-DD --end YYYY-MM-DD [--request-id UUID]Guarda un intervalo inclusivo con nombre y devuelve su identificador.
--duplicate-plan --id UUID --name NAME [--request-id UUID]Duplica un plan guardado con otro nombre y devuelve su identificador.
--open-plan --id UUIDAbre un plan guardado con sus intervalos y ajustes de repetición actuales.
--activate-set --calendar-set UUIDCambia el conjunto de calendarios activo conservando la fecha y la disposición actuales.
--working-days --start YYYY-MM-DD --end YYYY-MM-DDCuenta los días laborables según el horario activado y los calendarios de ausencias de día completo. Cuenta ambos extremos.
--shift-working-days --start YYYY-MM-DD --count INTEGERAvanza o retrocede por días laborables. El día inicial no cuenta.
--pause-chimes --minutes INTEGERPausa los avisos sonoros durante los minutos indicados, hasta siete días.
--resume-chimesFinaliza la pausa conservando el horario y el estado de activación de los avisos.
--export --start YYYY-MM-DD --end YYYY-MM-DD [--calendar-set UUID] [--plans UUID,UUID] [--events]Exporta un PNG de hasta dos años naturales. Incluye solo los planes solicitados. Los círculos de eventos se omiten salvo que se soliciten.

Las fechas de la API usan YYYY-MM-DD gregoriano en la zona horaria de la app. Los cálculos requieren un horario laboral activado. Las consultas se limitan a diez años y los desplazamientos a 2600 días laborables. Si falla la lectura de eventos, se devuelve un error en vez de tratar las ausencias como cero.

Usa el mismo UUID de solicitud y los mismos datos al reintentar crear o duplicar un plan. El reintento devuelve el identificador existente. Los datos distintos provocan un error. No reutilices ese UUID después de editar o eliminar el resultado. Un tiempo de espera agotado o una cancelación no deshacen un cambio ya aplicado.

popCalendar --sets --json
popCalendar --plans --name Holiday --json
popCalendar --create-plan --name Holiday --start 2027-08-02 --end 2027-08-13 --request-id REQUEST_UUID
popCalendar --duplicate-plan --id PLAN_UUID --name Variation --request-id NEW_REQUEST_UUID

--export escribe bytes PNG en la salida estándar. Redirígelos a un archivo. El intervalo solicitado queda resaltado y las ventanas normales y los ajustes guardados no cambian. La exportación CLI produce PNG, no PDF.

popCalendar --export --start 2027-01-01 --end 2027-12-31 --calendar-set SET_UUID --plans PLAN_UUID --events > calendar.png
Volver al índice

Resultados y errores

Los comandos de control esperan aceptación hasta 60 segundos de forma predeterminada. --wait es opcional. --no-wait solo confirma la entrega y no se puede combinar con --timeout ni usar para selección, datos o diagnóstico. La aceptación no significa que los eventos hayan terminado de cargarse.

Los comandos de datos devuelven JSON. Con --json, cada éxito o error es un objeto JSON en la salida estándar. Los errores incluyen errorCode, message y exitCode. Sin --json, se usa la salida de error estándar. --export devuelve bytes de imagen y no admite --json.

{"version":1,"status":"error","errorCode":"invalid_arguments","message":"Unknown option --example.","exitCode":64,"command":"open"}
Código de salidaQué hace
0Éxito
2Selección cancelada
3Tiempo de espera agotado
4Error al iniciar la app o conectar con ella
5Solicitud rechazada por la app
64Comando o argumentos no válidos
70Error interno o del canal de respuesta
128 + signalInterrumpido por una señal, incluido 130 para Control-C
Volver al índice

Diagnostica una conexión

--doctor puede iniciar la app en segundo plano. Su espera predeterminada es de diez segundos. No cambia permisos ni devuelve contenido del calendario. El diagnóstico JSON correcto aparece en result.diagnostics con connection igual a connected y permissionSource igual a app. Los errores incluyen un objeto diagnostics de nivel superior con permisos locales, que pueden diferir del estado no guardado de una app que no responde.

popCalendar --doctor --json
Volver al índice

Contenido y geometría

Comando u opciónQué hace
--presentationwindow de forma predeterminada, popup o fullscreen. Cierra una sesión activa antes de cambiar su presentación.
--modemonth, two-months, year, two-years, month-year o month-two-years. El valor predeterminado es year.
--dateYYYY-MM-DD gregoriano en la zona horaria de la app. Por defecto, la primera fecha del intervalo o el día de hoy.
--start, --endExtremos inclusivos en formato YYYY-MM-DD. Indica ambos, con start anterior o igual a end.
--clear-selectionBorra la selección. No se puede combinar con --start y --end.
--calendar-setUUID de un conjunto guardado o current para copiar el filtro activo. Obtén los identificadores con CLI o Atajos. Los desconocidos se rechazan.
--displaySolo para pantalla completa. current usa la pantalla del puntero, main la principal, o indica un UUID. Las pantallas desconectadas se sustituyen por una disponible.
--width, --heightDimensiones del contenido en puntos lógicos, cada una de 240 a 8192. Indica ambas. Las ventanas emergentes mantienen el tamaño solicitado desde el primer fotograma visible. Las ventanas normales redimensionables pueden crecer hasta alcanzar el mínimo legible. Los límites de la pantalla tienen prioridad. La CLI también acepta --size WIDTHxHEIGHT.
--anchorRectángulo de anclaje como x,y,width,height en coordenadas globales. No se puede combinar con x e y.
--x, --yPosición explícita en lugar de un anclaje. Indica ambas. Un panel con posición explícita no tiene flecha.
--coordinatesappkit usa la esquina inferior izquierda de la pantalla principal. top-left mide hacia abajo desde la superior izquierda. Las pantallas secundarias pueden tener coordenadas negativas. Se usan puntos, no píxeles.
--arrowauto, top, bottom, left, right o none. Indica el borde del panel que contiene la flecha. La posición puede invertirse para mantenerlo visible.
--callbackUn esquema URL personalizado registrado para devolver fechas confirmadas expresamente.

CLI usa los mismos nombres con el prefijo --, excepto selection=clear, que se convierte en --clear-selection. Las vistas a pantalla completa rechazan todas las opciones de geometría salvo display. Los parámetros desconocidos o duplicados, las fechas incorrectas y las URL de más de 16 KiB se rechazan por completo.

Volver al índice