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 índiceExecute 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" --helpOpcionalmente, 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 2027Sem 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 índiceEventos, 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 rangeA 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 í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. 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.jsonA 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 índiceAbra 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 pickerPara 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ção | O que faz |
|---|---|
--help | Exibe a referência completa de comandos e opções. |
--version | Exibe 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 UUID | Abre um plano salvo com os intervalos e ajustes de repetição atuais. |
--activate-set --calendar-set UUID | Muda o conjunto ativo mantendo a data e o layout atuais. |
--working-days --start YYYY-MM-DD --end YYYY-MM-DD | Conta 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 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 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ída | O que faz |
|---|---|
0 | Sucesso |
2 | Seleção cancelada |
3 | Tempo limite excedido |
4 | Falha ao iniciar o app ou conectar |
5 | Solicitação rejeitada pelo app |
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 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ção | O que faz |
|---|---|
--presentation | window por padrão, popup ou fullscreen. Feche uma sessão ativa antes de mudar sua apresentação. |
--mode | month, two-months, year, two-years, month-year ou month-two-years. O padrão é year. |
--date | YYYY-MM-DD gregoriano no fuso horário do app. Por padrã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 salvo ou current para copiar o filtro ativo. Obtenha IDs via CLI ou Atalhos. IDs desconhecidos são rejeitados. |
--display | Apenas 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, --height | Dimensõ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. |
--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 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. |
--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 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