Documentação de automação
Referência da linha de comandos
Integre o popCalendar na sua alternativa ao Dock ou noutras ferramentas para Mac. Abra calendários, escolha datas, gira planos e exporte imagens através da 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 a sua ferramenta
Adicione o popCalendar à sua alternativa ao Dock, lançador de aplicações, utilitário da barra de menus ou qualquer outra ferramenta para Mac. Ofereça uma experiência rica de calendário sem ter de a implementar de raiz, utilizando janelas nativas de calendário, pop-ups ancorados e seleção de datas através da CLI.
Os programadores podem contactar-nos para obter um código promocional gratuito do popCalendar e apoio prático durante o desenvolvimento de uma integração.
Cada ferramenta que implementar uma integração com o popCalendar terá uma secção dedicada em popcalendar.app como uma integração com suporte oficial. Avise-nos quando a sua estiver pronta.
Voltar ao índiceExecute a partir do pacote da aplicação
Com o popCalendar instalado, não é necessário um pacote CLI separado. Execute o ficheiro principal pelo caminho completo. Todos os comandos começam com --. Executar sem um comando abre a aplicação normalmente.
"/Applications/popCalendar.app/Contents/MacOS/popCalendar" --helpOpcionalmente, acrescente o diretório do executável ao PATH da sessão atual do terminal. Pode adicionar a mesma linha à configuração da shell. Use a localização real se a aplicação foi movida ou renomeada. 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 Mostrar um calendário no Terminal
Use --terminal para mostrar o calendário sem abrir uma janela de calendário. Primeiro, ative Calendários no Terminal em Definições > Automação e Privacidade. Pré-visualização abre um painel de exemplo com comandos que pode copiar. Os calendários básicos funcionam localmente. Os dados privados pedidos são lidos pela aplicação 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 2027Sem um esquema explícito, é mostrado um ano inteiro se couber ou um mês caso contrário. O modo interativo adapta-se ao redimensionamento até escolher um esquema ou selecionar um intervalo. Pipes, JSON e a saída apenas de agenda usam um mês por predefinição.
Voltar ao índiceEventos, planos e dias úteis
Use --events para incluir eventos, --agenda para uma lista de eventos, --plans para marcar planos guardados e --working-days para o seu horário de trabalho. O filtro de conjunto de calendários aplica-se apenas a esse comando e não altera o conjunto ativo. --search pesquisa nos títulos e locais. Conceda acesso aos calendários na aplicação antes de pedir 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 rangeA opção week abrange os sete dias seguintes a partir de --date ou de hoje. Um intervalo inclui ambas as extremidades. Sem uma seleção explícita, os eventos de range abrangem os meses apresentados. As datas e os títulos usam o calendário gregoriano.
Voltar ao índiceNavegar 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. Prima v para marcar o início e o fim de um intervalo, c para o limpar, g para ir a uma data, / para pesquisar e ? para obter ajuda. Prima 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. Prima s para o conjunto de calendários seguinte, r para atualizar e PageUp/PageDown ou Space para deslocar.
Os comandos por extenso também funcionam e não distinguem maiúsculas de minúsculas. No modo de resposta imediata, prima primeiro a tecla de dois-pontos, escreva um comando e prima Enter. Se o rodapé pedir Enter, escreva o comando diretamente e prima 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 entre 1 e 24 meses. Indique --start e --end em conjunto, sem outra opção de data ou modo. Use --time-zone, --first-weekday e --week-numbers para configurar o calendário. --width aceita entre 32 e 240 colunas, --limit entre 1 e 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.jsonA saída redirecionada é texto simples. --json devolve dados estruturados sem formatação ANSI e não pode ser combinado com --interactive ou --color always. Os comandos do Terminal apenas leem dados e não alteram eventos, planos ou conjuntos de calendários.
Voltar ao índiceAbra e controle calendários
As opções aceitam --opção valor ou --opção=valor. A sessão predefinida é cli. Reutilizar uma sessão atualiza a mesma janela. Use nomes diferentes para janelas independentes. Todos os seis modos são suportados.
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 pickerPara uma sobreposição em ecrã completo, use --presentation fullscreen com --display current, main ou um UUID de ecrã. Ocupa um ecrã sem criar um Espaço do macOS. Escape ou alternar a mesma sessão fecha-a. As sessões em ecrã completo rejeitam tamanho, posição, âncora, seta e coordenadas. Feche a sessão antes de mudar a apresentação.
popCalendar --toggle --session overview --presentation fullscreen --mode two-years --display current Voltar ao índice Devolva uma seleção confirmada
--select abre um seletor e aguarda confirmação. O tempo limite predefinido é de 300 segundos. Defina --timeout entre 1 e 86400. Escape, fechar o seletor ou Control-C cancela a operação. São devolvidos 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 devolvidos 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 automatização.
| Comando ou opção | O que faz |
|---|---|
--help | Mostra a referência completa de comandos e opções. |
--version | Mostra a versão e a compilação da aplicação. |
--capabilities [--json] | Devolve os comandos e limites suportados sem abrir a aplicação. |
--doctor [--json] [--timeout SECONDS] | Verifica a identidade da aplicação, as permissões e a comunicação com ela. |
--sets [--json] | Devolve nomes e IDs dos conjuntos de calendários guardados. |
--sessions [--json] | Devolve os IDs das sessões de integração abertas no Mac. |
--plans [--name SEARCH] [--id UUID] [--json] | Devolve planos guardados, os respetivos 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] | Guarda um intervalo inclusivo com nome e devolve o ID do plano. |
--duplicate-plan --id UUID --name NAME [--request-id UUID] | Duplica um plano guardado com outro nome e devolve o seu ID. |
--open-plan --id UUID | Abre um plano guardado com os intervalos e definições de repetição atuais. |
--activate-set --calendar-set UUID | Muda o conjunto ativo mantendo a data e a disposição atuais. |
--working-days --start YYYY-MM-DD --end YYYY-MM-DD | Conta os dias úteis usando o horário ativado e os calendários de ausências de dia inteiro. Ambos os extremos contam. |
--shift-working-days --start YYYY-MM-DD --count INTEGER | Avança ou retrocede por dias úteis. O dia inicial não conta. |
--pause-chimes --minutes INTEGER | Pausa os sinais sonoros pelo número de minutos indicado, até sete dias. |
--resume-chimes | Encerra 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 da aplicação. Os cálculos exigem um horário de trabalho ativado. As consultas limitam-se a dez anos e os deslocamentos a 2600 dias úteis. As falhas na leitura de eventos geram um erro em vez de considerar zero ausências.
Use o mesmo UUID de pedido e dados idênticos ao repetir a criação ou duplicação de um plano. A repetição devolve o ID existente. Dados diferentes causam um erro. Não reutilize o UUID após editar ou apagar 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 escreve bytes PNG na saída padrão. Redirecione-os para um ficheiro. O intervalo pedido fica destacado e as janelas normais e as definições guardadas 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
Os comandos de controlo aguardam aceitação até 60 segundos por predefiniçã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.
Os comandos de dados devolvem JSON. Com --json, sucesso ou falha é um objeto JSON na saída padrão. Os erros incluem errorCode, message e exitCode. Sem --json, os erros usam a saída de erro padrão. --export devolve 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ída | O que faz |
|---|---|
0 | Sucesso |
2 | Seleção cancelada |
3 | Tempo limite excedido |
4 | Falha ao iniciar a aplicação ou estabelecer a ligação |
5 | Pedido rejeitado pela aplicação |
64 | Comando ou argumentos inválidos |
70 | Erro interno ou no canal de resposta |
128 + signal | Interrompido por um sinal, incluindo 130 para Control-C |
Diagnostique uma ligação
--doctor pode iniciar a aplicação em segundo plano. O tempo limite predefinido é de dez segundos. Não muda permissões nem devolve conteúdo do calendário. Os diagnósticos JSON bem-sucedidos aparecem em result.diagnostics com connection definido como connected e permissionSource como app. As falhas incluem um objeto diagnostics no nível superior com permissões locais, que podem diferir do estado não guardado de uma aplicação sem resposta.
popCalendar --doctor --json Voltar ao índice Conteúdo e geometria
| Comando ou opção | O que faz |
|---|---|
--presentation | window por predefinição, popup ou fullscreen. Feche uma sessão ativa antes de mudar a apresentação. |
--mode | month, two-months, year, two-years, month-year ou month-two-years. A predefinição é year. |
--date | YYYY-MM-DD gregoriano no fuso horário da aplicação. Por predefinição, a primeira data do intervalo ou hoje. |
--start, --end | Extremos inclusivos em YYYY-MM-DD. Informe ambos, com start anterior ou igual a end. |
--clear-selection | Limpa a seleção. Não pode ser combinado com --start e --end. |
--calendar-set | UUID de um conjunto guardado ou current para copiar o filtro ativo. Obtenha IDs através de CLI ou Atalhos. Os IDs desconhecidos são rejeitados. |
--display | Apenas para ecrã completo. current usa o ecrã do ponteiro, main usa o principal, ou indique um UUID. Os ecrãs desligados são substituídos por um disponível. |
--width, --height | Dimensões do conteúdo em pontos lógicos, cada uma de 240 a 8192. Indique ambas. As janelas pop-up mantêm o tamanho pedido desde o primeiro fotograma visível. As janelas normais redimensionáveis podem aumentar até atingir o mínimo legível. Os limites do ecrã têm prioridade. A CLI também aceita --size WIDTHxHEIGHT. |
--anchor | Retângulo da âncora como x,y,width,height em coordenadas globais. Não pode ser combinado com x e y. |
--x, --y | Posição explícita em vez de uma âncora. Informe ambas. Um painel com posição explícita não tem seta. |
--coordinates | appkit usa o canto inferior esquerdo do ecrã principal. top-left mede para baixo a partir do canto superior esquerdo. Os ecrãs secundários podem ter coordenadas negativas. Os valores são pontos, não píxeis. |
--arrow | auto, 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. |
--callback | Um esquema de URL personalizado registado para devolver datas explicitamente confirmadas. |
CLI usa os mesmos nomes com o prefixo --, exceto selection=clear, que passa a --clear-selection. As sobreposições em ecrã completo rejeitam toda a geometria exceto display. Parâmetros desconhecidos ou duplicados, datas malformadas e URLs acima de 16 KiB são rejeitados por completo.
Voltar ao índice