Documentação de automação

Referência da linha de comando

Integre o popCalendar à sua alternativa ao Dock ou a outras ferramentas para Mac. Abra calendários, escolha datas, gerencie planos e exporte imagens pela CLI.

Estes guias abrangem o popCalendar 1.3 e versões posteriores. Algumas ações exigem uma versão mais recente do sistema, conforme indicado abaixo.

Uma experiência completa de calendário para sua ferramenta

Adicione o popCalendar à sua alternativa ao Dock, iniciador de apps, utilitário da barra de menus ou qualquer outra ferramenta para Mac. Ofereça uma experiência rica de calendário sem precisar implementá-la por conta própria, usando janelas nativas de calendário, pop-ups ancorados e seleção de datas pela CLI.

Desenvolvedores podem entrar em contato conosco para receber um código promocional gratuito do popCalendar e suporte prático durante o desenvolvimento de uma integração.

Entre em contato pelo support@apptrust.app

Toda ferramenta que implementar uma integração com o popCalendar receberá uma seção dedicada no popcalendar.app como uma integração com suporte oficial. Avise quando a sua estiver pronta.

Voltar ao índice

Execute pelo pacote do app

Com o popCalendar instalado, não é necessário um pacote CLI separado. Execute o arquivo principal pelo caminho completo. Todo comando começa com --. Executar sem um comando abre o app normalmente.

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

Opcionalmente, acrescente o diretório do executável ao PATH da sessão atual do terminal. Você pode adicionar a mesma linha à configuração do shell. Use a localização real se o app foi movido ou renomeado. O executável do Setapp também se chama popCalendar. Use um caminho completo para escolher a edição quando ambas estiverem instaladas.

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

Exibir um calendário no Terminal

Use --terminal para exibir o calendário sem abrir uma janela de calendário. Primeiro, ative Calendários no Terminal em Ajustes > Automação e Privacidade. Prévia abre um painel de exemplo com comandos que você pode copiar. Calendários básicos funcionam localmente. Os dados privados solicitados são lidos pelo app em 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

Sem um layout explícito, um ano inteiro é exibido se couber ou um mês caso contrário. O modo interativo se adapta ao redimensionamento até você escolher um layout ou selecionar um intervalo. Pipes, JSON e a saída somente de agenda usam um mês por padrão.

Voltar ao índice

Eventos, planos e dias úteis

Use --events para incluir eventos, --agenda para uma lista de eventos, --plans para marcar planos salvos e --working-days para sua escala de trabalho. O filtro de conjunto de calendários só vale para esse comando e não altera o conjunto ativo. --search busca nos títulos e locais. Conceda acesso aos calendários no 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

A opção week abrange os próximos sete dias a partir de --date ou de hoje. Um intervalo inclui as duas extremidades. Sem uma seleção explícita, os eventos de range abrangem os meses exibidos. Datas e títulos usam o calendário gregoriano.

Voltar ao índice

Navegar no modo interativo

Use as setas ou h/j/k/l para percorrer os dias, n/p para os períodos, m/y para mês ou ano e t para hoje. Pressione v para marcar o início e o fim de um intervalo, c para limpá-lo, g para ir a uma data, / para buscar e ? para obter ajuda. Pressione q ou Escape para sair.

Alterne eventos com e, agenda com a, planos com b, dias úteis com d e números das semanas com w. Pressione s para o próximo conjunto de calendários, r para atualizar e PageUp/PageDown ou Space para rolar.

Comandos por extenso também funcionam e não diferenciam maiúsculas de minúsculas. No modo de resposta imediata, pressione primeiro a tecla de dois-pontos, digite um comando e pressione Enter. Se o rodapé pedir Enter, digite o comando diretamente e pressione Enter. Escape cancela primeiro uma entrada ativa antes de sair.

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
Voltar ao índice

Opções de saída do Terminal

Escolha uma data, um mês, um ano, um modo ou de 1 a 24 meses. Informe --start e --end juntos, sem outra opção de data ou modo. Use --time-zone, --first-weekday e --week-numbers para configurar o calendário. --width aceita de 32 a 240 colunas, --limit de 1 a 500 eventos e --color aceita auto, always ou 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

A saída redirecionada é texto simples. --json retorna dados estruturados sem formatação ANSI e não pode ser combinado com --interactive ou --color always. Os comandos do Terminal só leem dados e não alteram eventos, planos ou conjuntos de calendários.

Voltar ao índice

Abra e controle calendários

As opções aceitam --opção valor ou --opção=valor. A sessão padrão é cli. Reutilizar uma sessão atualiza a mesma janela. Use nomes diferentes para janelas independentes. Todos os seis modos são compatíveis.

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 uma sobreposição em tela cheia, use --presentation fullscreen com --display current, main ou um UUID de monitor. Ela ocupa um monitor sem criar um Espaço do macOS. Escape ou alternar a mesma sessão a fecha. Sessões em tela cheia rejeitam tamanho, posição, âncora, seta e coordenadas. Feche a sessão antes de mudar sua apresentação.

popCalendar --toggle --session overview --presentation fullscreen --mode two-years --display current
Voltar ao índice

Retorne uma seleção confirmada

--select abre um seletor e aguarda confirmação. O tempo limite padrão é 300 segundos. Defina --timeout entre 1 e 86400. Escape, fechar o seletor ou Control-C cancela a operação. São retornados até 128 intervalos separados do último painel utilizado. Sem --json, cada linha contém START END. Ambas as datas são incluídas.

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"}]}
Voltar ao índice

Planos, dias úteis e imagens

Substitua SET_UUID e PLAN_UUID pelos IDs retornados por --sets e --plans. Use UUIDs diferentes para REQUEST_UUID e NEW_REQUEST_UUID. As permissões necessárias estão descritas na visão geral da automação.

Comando ou opçãoO que faz
--helpExibe a referência completa de comandos e opções.
--versionExibe a versão e a compilação do app.
--capabilities [--json]Retorna comandos e limites compatíveis sem abrir o app.
--doctor [--json] [--timeout SECONDS]Verifica a identidade do app, as permissões e a comunicação com ele.
--sets [--json]Retorna nomes e IDs dos conjuntos de calendários salvos.
--sessions [--json]Retorna IDs de sessões de integração abertas no Mac.
--plans [--name SEARCH] [--id UUID] [--json]Retorna planos salvos, seus intervalos e informações de repetição. Filtre por nome ou ID.
--create-plan --name NAME --start YYYY-MM-DD --end YYYY-MM-DD [--request-id UUID]Salva um intervalo inclusivo com nome e retorna o ID do plano.
--duplicate-plan --id UUID --name NAME [--request-id UUID]Duplica um plano salvo com outro nome e retorna seu ID.
--open-plan --id UUIDAbre um plano salvo com os intervalos e ajustes de repetição atuais.
--activate-set --calendar-set UUIDMuda o conjunto ativo mantendo a data e o layout atuais.
--working-days --start YYYY-MM-DD --end YYYY-MM-DDConta os dias úteis usando a jornada ativada e os calendários de ausências de dia inteiro. Os dois extremos contam.
--shift-working-days --start YYYY-MM-DD --count INTEGERAvança ou retrocede por dias úteis. O dia inicial não conta.
--pause-chimes --minutes INTEGERPausa os sinais sonoros pelo número de minutos indicado, até sete dias.
--resume-chimesEncerra a pausa preservando a programação e o estado de ativação dos sinais sonoros.
--export --start YYYY-MM-DD --end YYYY-MM-DD [--calendar-set UUID] [--plans UUID,UUID] [--events]Exporta um PNG de até dois anos civis. Inclui apenas os planos solicitados. Círculos de eventos são omitidos, a menos que solicitados.

As datas da API usam YYYY-MM-DD gregoriano no fuso horário do app. Os cálculos exigem uma jornada de trabalho ativada. Consultas se limitam a dez anos e deslocamentos a 2.600 dias úteis. Falhas na leitura de eventos geram um erro em vez de considerar zero ausências.

Use o mesmo UUID de solicitação e dados idênticos ao repetir a criação ou duplicação de um plano. A repetição retorna o ID existente. Dados diferentes causam erro. Não reutilize o UUID após editar ou excluir o resultado. Um tempo limite ou cancelamento não desfaz uma alteração já aplicada.

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 grava bytes PNG na saída padrão. Redirecione-os para um arquivo. O intervalo solicitado fica destacado e as janelas normais e os ajustes salvos não mudam. A exportação CLI produz PNG, não PDF.

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

Resultados e falhas

Comandos de controle aguardam aceitação por até 60 segundos por padrão. --wait é opcional. --no-wait confirma apenas a entrega e não pode ser combinado com --timeout nem usado para seleção, dados ou diagnóstico. A aceitação não significa que os eventos terminaram de carregar.

Comandos de dados retornam JSON. Com --json, sucesso ou falha é um objeto JSON na saída padrão. Erros incluem errorCode, message e exitCode. Sem --json, erros usam a saída de erro padrão. --export retorna bytes de imagem e não aceita --json.

{"version":1,"status":"error","errorCode":"invalid_arguments","message":"Unknown option --example.","exitCode":64,"command":"open"}
Código de saídaO que faz
0Sucesso
2Seleção cancelada
3Tempo limite excedido
4Falha ao iniciar o app ou conectar
5Solicitação rejeitada pelo app
64Comando ou argumentos inválidos
70Erro interno ou no canal de resposta
128 + signalInterrompido por um sinal, incluindo 130 para Control-C
Voltar ao índice

Diagnostique uma conexão

--doctor pode iniciar o app em segundo plano. O tempo limite padrão é dez segundos. Ele não muda permissões nem retorna conteúdo do calendário. Diagnósticos JSON bem-sucedidos aparecem em result.diagnostics com connection definido como connected e permissionSource como app. Falhas incluem um objeto diagnostics no nível superior com permissões locais, que podem diferir do estado não salvo de um app sem resposta.

popCalendar --doctor --json
Voltar ao índice

Conteúdo e geometria

Comando ou opçãoO que faz
--presentationwindow por padrão, popup ou fullscreen. Feche uma sessão ativa antes de mudar sua apresentação.
--modemonth, two-months, year, two-years, month-year ou month-two-years. O padrão é year.
--dateYYYY-MM-DD gregoriano no fuso horário do app. Por padrão, a primeira data do intervalo ou hoje.
--start, --endExtremos inclusivos em YYYY-MM-DD. Informe ambos, com start anterior ou igual a end.
--clear-selectionLimpa a seleção. Não pode ser combinado com --start e --end.
--calendar-setUUID de um conjunto salvo ou current para copiar o filtro ativo. Obtenha IDs via CLI ou Atalhos. IDs desconhecidos são rejeitados.
--displayApenas para tela cheia. current usa o monitor do ponteiro, main usa o principal, ou informe um UUID. Monitores desconectados são substituídos por um disponível.
--width, --heightDimensões do conteúdo em pontos lógicos, cada uma de 240 a 8192. Informe ambas. Os pop-ups mantêm o tamanho solicitado desde o primeiro quadro visível. Janelas comuns redimensionáveis podem aumentar até atingir o mínimo legível. Os limites da tela têm prioridade. A CLI também aceita --size WIDTHxHEIGHT.
--anchorRetângulo da âncora como x,y,width,height em coordenadas globais. Não pode ser combinado com x e y.
--x, --yPosição explícita em vez de uma âncora. Informe ambas. Um painel com posição explícita não tem seta.
--coordinatesappkit usa o canto inferior esquerdo do monitor principal. top-left mede para baixo a partir do canto superior esquerdo. Monitores secundários podem ter coordenadas negativas. Os valores são pontos, não pixels.
--arrowauto, top, bottom, left, right ou none. Nomeia a borda do painel que contém a seta. A posição pode inverter para manter o painel visível.
--callbackUm esquema de URL personalizado registrado para retornar datas explicitamente confirmadas.

CLI usa os mesmos nomes com prefixo --, exceto selection=clear, que vira --clear-selection. Sobreposições em tela cheia rejeitam toda geometria exceto display. Parâmetros desconhecidos ou duplicados, datas malformadas e URLs acima de 16 KiB são rejeitados por completo.

Voltar ao índice