Google Calendar CLI: gerencie eventos pelo terminal

Como usar um Google Calendar CLI pelo terminal?

Autentique-se uma vez e depois use nylas calendar list, nylas calendar events list, nylas calendar events create e nylas calendar availability find. Isso permite um fluxo de trabalho com o Google Calendar pelo terminal sem criar credenciais OAuth ou escrever código com a Calendar API.

Você quer gerenciar o Google Calendar pela linha de comando. O caminho oficial exige 6 passos antes de tocar em um único evento:

1. Criar um projeto GCP no Google Cloud Console
2. Ativar a Google Calendar API
3. Configurar a tela de consentimento OAuth (apps externos passam pela revisão de verificação de marca do Google, que pode levar até seis semanas para escopos sensíveis)
4. Criar credenciais OAuth 2.0 ou um service account se precisar de delegação em todo o domínio
5. Definir escopos de calendário (https://www.googleapis.com/auth/calendar para leitura/escrita, ou o mais restrito calendar.events)
6. Escrever código para trocar tokens e fazer chamadas à API

Para um app interno, a configuração do GCP em si é rápida. A parte custosa é a revisão OAuth para qualquer app não interno, além da cota por usuário: a Calendar API é limitada a 600 requisições por minuto por projeto por padrão, então automações pesadas precisam solicitar aumento de cota ao Google. Para quem só quer verificar a próxima reunião pelo terminal, é configuração demais.

1. Instalação (pule se já estiver configurado)

O Nylas CLI instala em menos de 30 segundos no macOS e Linux via Homebrew e oferece 4 métodos de instalação no total. O binário tem cerca de 25 MB e detecta automaticamente a arquitetura do seu sistema operacional durante a configuração, sem necessidade de configuração manual após a instalação.

Execute brew install nylas/nylas-cli/nylas ou consulte o guia de primeiros passos para opções de instalação via shell script, PowerShell e Go.

2. Autenticar com o Google

Autenticar-se com o Google Calendar pelo Nylas CLI leva um único comando em vez dos 6 passos de configuração do projeto GCP exigidos pela Google Calendar API nativa. A CLI abre um fluxo OAuth2 no navegador, troca o código de autorização e armazena as credenciais localmente. A renovação do token acontece automaticamente em cada chamada subsequente.

O comando nylas auth login solicita os escopos calendar e email do Google. Todo o fluxo é concluído em menos de 60 segundos, e o token armazenado persiste entre sessões do terminal até que você revogue o acesso explicitamente.

nylas auth login

Após a autenticação, verifique a conexão listando os calendários. Uma resposta bem-sucedida mostra todos os calendários visíveis para a conta Google autenticada, incluindo calendários compartilhados e secundários. A maioria dos usuários do Google Workspace tem de 3 a 5 calendários visíveis por padrão.

nylas calendar list

Você deve ver seus calendários do Google listados por nome e ID.

3. Calendários secundários e transferências de propriedade

O Google Calendar trata calendários secundários de forma diferente dos primários durante eventos do ciclo de vida da conta. Quando um funcionário sai de um domínio Google Workspace, o calendário principal é excluído após 20 dias por padrão, mas calendários secundários criados por ele podem ficar órfãos. De acordo com a documentação de administração do Google Workspace, administradores devem transferir manualmente a propriedade do calendário antes de excluir a conta do usuário.

O Nylas CLI pode listar todos os calendários visíveis para um grant e indicar quais são primários vs. secundários. Isso é útil para auditar a propriedade antes do desligamento de funcionários. Um usuário Workspace típico com 2 a 3 calendários compartilhados deve executar essa verificação de inventário trimestralmente.

# Listar todos os calendários e identificar os não-primários
nylas calendar list --json | \
  jq -r '.[] | "\(.name) | primary=\(.is_primary) | id=\(.id)"'

# Buscar eventos de um calendário compartilhado ou secundário específico
nylas calendar events list --calendar cal_team_launch --days 14

Para equipes que usam Workspace intensivamente, inventário e propriedade fazem parte das operações de calendário. O guia de mudanças de propriedade do Google Calendar cobre fluxos de desligamento e transferências programáticas de calendários compartilhados.

4. Limites de administração do Workspace

O Google Workspace distingue três modelos de autenticação que desenvolvedores frequentemente confundem: grants OAuth de usuário (o que o Nylas CLI usa), service accounts para chamadas servidor-a-servidor e delegação em todo o domínio para acesso em nível de administrador a todos os usuários. De acordo com a visão geral de autenticação do Google Workspace, a delegação em todo o domínio requer que um Super Admin autorize escopos OAuth específicos por service account.

O Nylas CLI opera no escopo OAuth de nível de usuário, que cobre calendários pessoais e compartilhados visíveis para o usuário autenticado. Para fluxos que precisam ler ou escrever em mais de 10 calendários de funcionários simultaneamente, a delegação em todo o domínio por meio de um service account é a abordagem padrão do Google. O acesso a calendários do Yahoo e iCloud é principalmente um problema de conta pessoal, enquanto o gerenciamento de calendários do Google Workspace é um problema de política de tenant e ciclo de vida.

5. Fluxos de trabalho com Google Meet e tipos de evento

O Google Calendar automaticamente anexa detalhes de conferência do Google Meet a eventos criados com pelo menos um participante. O Google Meet gera mais de 100 milhões de links de reunião diariamente, de acordo com o blog do Workspace do Google, então a maioria dos scripts de automação de calendário precisa lidar com o campo conferencing. O Nylas CLI expõe esses detalhes do Meet na saída JSON junto com metadados de tempo focado, ausência do escritório e localização de trabalho.

Criar um evento com participantes pelo Nylas CLI aciona o recurso de conferência automática do Google. A CLI envia a lista de participantes e o intervalo de tempo, e o Google Calendar adiciona o link do Meet no lado do servidor. O objeto de evento resultante inclui um campo conferencing.details.url com o link de acesso.

# Criar uma reunião e deixar o Google anexar detalhes de conferência
nylas calendar events create \
  --title "Project Kickoff" \
  --start "2026-04-02 14:00" \
  --end "2026-04-02 15:00" \
  --participant alice@company.com \
  --participant bob@company.com

# Inspecionar links do Meet e metadados específicos do Google
nylas calendar events list --days 7 --json | \
  jq '.[] | {title: .title, meet: .conferencing, metadata: .metadata}'

6. Disponibilidade entre calendários Workspace e pessoais

Verificar disponibilidade no Google Calendar exige consultar o endpoint da FreeBusy API com IDs de calendário, intervalos de tempo e deslocamentos de fuso horário. O Nylas CLI encapsula isso em um único comando que verifica slots livres/ocupados em todos os calendários visíveis. Para equipes onde funcionários têm tanto um Gmail pessoal quanto uma conta Workspace, as verificações de disponibilidade precisam considerar ambas as identidades para evitar conflitos de agendamento.

O comando nylas calendar availability check retorna slots de horário livres e ocupados para o usuário autenticado. O comando nylas calendar availability find recebe 2 ou mais endereços de e-mail de participantes e encontra horários mútuos disponíveis. Ambos os comandos aceitam as flags --start e --end para restringir a janela de busca.

# Verificar seus próprios slots livres/ocupados
nylas calendar availability check

# Encontrar um slot de 30 minutos entre colegas
nylas calendar availability find \
  --participants alice@company.com,bob@company.com \
  --duration 30

# Restringir a busca a um intervalo de datas
nylas calendar availability find \
  --participants alice@company.com,bob@company.com \
  --duration 60 \
  --start "2026-04-01" \
  --end "2026-04-05"

7. Comandos principais do Google Calendar

O Nylas CLI oferece 4 operações principais de eventos para o Google Calendar: listar, criar, atualizar e excluir. Esses comandos mapeiam diretamente para o recurso Events da Google Calendar API, mas eliminam as 40-80 linhas de boilerplate em Python que a API nativa exige. Cada comando funciona da mesma forma independentemente de o calendário alvo ser primário, secundário ou compartilhado do Workspace.

O comando nylas calendar events list retorna eventos dos próximos N dias e suporta --show-tz para exibir informações de fuso horário ao lado de cada evento. Criar um evento de dia inteiro usa a flag --all-day com um valor --start somente com data. Atualizações exigem o ID do evento, que pode ser obtido na saída do comando de listagem.

# Listar eventos futuros
nylas calendar events list --days 14 --show-tz

# Criar um evento de dia inteiro
nylas calendar events create \
  --title "Company Holiday" \
  --start "2026-04-10" \
  --all-day

# Reagendar um evento existente
nylas calendar events update event_abc123 \
  --title "Sprint Planning (Moved)" \
  --start "2026-04-01 11:00" \
  --end "2026-04-01 12:00"

# Excluir um evento
nylas calendar events delete event_abc123

8. Saída JSON para scripts

Todos os comandos de calendário do Nylas CLI suportam a flag --json, que produz JSON estruturado em vez do formato de tabela padrão. A saída JSON inclui de 15 a 20 campos por evento dependendo do provedor, cobrindo horários de início/fim, participantes, conferência, regras de recorrência e metadados específicos do provedor. Redirecionar o JSON para o jq permite filtragem, agrupamento e relatórios sem escrever um script completo.

A estrutura JSON segue o esquema de eventos do Nylas, onde os dados de horário ficam na chave when e a conferência na chave conferencing. Eventos do Google Calendar incluem campos de metadados adicionais como color_id e event_type que outros provedores não expõem. Estes exemplos mostram padrões comuns para extrair títulos, contar eventos por dia e filtrar slots livres.

# Obter todos os eventos futuros como JSON
nylas calendar events list --days 7 --json

# Extrair títulos de eventos
nylas calendar events list --json | jq '.[].title'

# Contar eventos por dia nesta semana
nylas calendar events list --days 7 --json | \
  jq 'group_by(.when.start_date) | map({date: .[0].when.start_date, count: length})'

# Buscar apenas slots livres
nylas calendar availability check --json | \
  jq '.time_slots[] | select(.status == "free")'

Google Calendar API vs Nylas CLI

A Google Calendar API exige um projeto GCP, tela de consentimento OAuth e 40-80 linhas de Python para listar eventos. O Nylas CLI alcança o mesmo resultado com um único comando após uma instalação de 30 segundos. Esta comparação cobre 7 dimensões, desde o tempo de configuração inicial até as linhas de código necessárias para operações CRUD básicas de calendário.

Dicas específicas do Google Calendar

O Google Calendar tem vários recursos específicos do provedor que não existem nos calendários do Outlook, Yahoo ou iCloud. Isso inclui 11 rótulos de cores numéricas, expansão de eventos recorrentes baseada em RRULE, geração automática de links do Google Meet e tipos de evento como tempo focado e localização de trabalho. Entender essas 4 áreas ajuda a evitar surpresas ao fazer scripts com dados do Google Calendar pelo Nylas CLI.

Rótulos de cores

O Google Calendar atribui IDs de cores numéricas de 1 a 11 para eventos, com cada número mapeando para uma cor nomeada na paleta do Google (por exemplo, color ID 11 é "Tomato"). Ao listar eventos com --json, o campo color_id aparece no objeto de metadados. Filtrar por color ID é útil para scripts que categorizam eventos por projeto ou prioridade.

# Listar eventos com uma cor específica (ex: "Tomato" = color_id 11)
nylas calendar events list --json | \
  jq '.[] | select(.metadata.color_id == "11") | .title'

Eventos recorrentes

O Google Calendar armazena eventos recorrentes usando padrões RRULE definidos na RFC 5545. Uma daily standup semanal, por exemplo, é armazenada como um único evento principal com um RRULE como FREQ=WEEKLY;BYDAY=MO, e o Google o expande em ocorrências individuais. Quando o Nylas CLI lista eventos, cada ocorrência aparece como um objeto de evento separado. O campo master_event_id vincula cada ocorrência de volta ao evento principal original, o que é útil para edição em lote de uma série inteira.

# Listar eventos e filtrar por uma série recorrente
nylas calendar events list --json | \
  jq '.[] | select(.master_event_id == "event_abc123") | {title, start: .when.start_time}'

Links do Google Meet

O Google Calendar gera automaticamente um link de acesso ao Meet para eventos criados com pelo menos 1 participante por meio de uma conta Google Workspace ou Gmail pessoal. Os dados de conferência aparecem no campo conferencing do objeto de evento JSON. Eventos sem participantes, como lembretes de dia inteiro ou blocos de tempo focado, não recebem links do Meet. O filtro jq a seguir extrai apenas eventos que têm conferência anexada.

# Encontrar eventos com links do Google Meet
nylas calendar events list --json | \
  jq '.[] | select(.conferencing != null) | {title, meet: .conferencing.details.url}'

Localização de trabalho e calendários de tempo focado

O Google Calendar introduziu 3 tipos de evento especiais que outros provedores não suportam: tempo focado, ausência do escritório e localização de trabalho. Esses tipos de evento afetam a disponibilidade de forma diferente das reuniões regulares. Um bloco de tempo focado, por exemplo, marca o usuário como ocupado mas recusa automaticamente novos convites de reunião. Um evento de ausência do escritório recusa automaticamente e envia uma mensagem personalizada ao organizador. Se seu script de agendamento trata todos os eventos como reuniões regulares, ele vai interpretar incorretamente esses tipos específicos do Google. Inspecione os campos metadata e status na saída JSON para distingui-los.

# Inspecionar metadados de eventos específicos do Google
nylas calendar events list --days 7 --json | \
  jq '.[] | {title: .title, status: .status, metadata: .metadata}'

Próximos passos

Este guia cobriu CRUD de eventos do Google Calendar, verificações de disponibilidade e recursos específicos do provedor como links do Meet e blocos de tempo focado. O Nylas CLI suporta 6 provedores de calendário com a mesma sintaxe de comandos, então a maioria desses padrões se aplica diretamente aos calendários do Outlook, Yahoo e iCloud.

• Gerenciar eventos de calendário pelo terminal -- agendamento com horário de verão, bloqueio de fuso horário e localizador de reuniões com IA
• Ferramentas CLI de e-mail comparadas -- compare ferramentas de e-mail no terminal que também precisam de acesso ao calendário
• CLI de agente de IA para e-mail e calendário -- exponha comandos de calendário como ferramentas JSON para agentes LLM
• Listar e-mails do Gmail pela linha de comando -- leia e pesquise sua caixa de entrada sem configuração da Google API
• Enviar e-mail pelo terminal -- componha e envie e-mails pela CLI
• Mudanças de propriedade do Google Calendar -- calendários órfãos excluídos em 27 de abril, nova API de transferência em junho
• Paginação e sincronização da Google Calendar API -- nextPageToken, syncToken, recuperação de 410 Gone e expansão de eventos recorrentes
• Dê acesso de e-mail a agentes de IA via MCP -- conecte o Claude ou Cursor ao seu calendário e e-mail
• Sincronizar calendários entre provedores -- ICS, CalDAV e sincronização de calendário baseada em API comparados
• Melhores ferramentas CLI de calendário comparadas -- gcalcli, khal, calcurse, remind e Nylas CLI
• Referência completa de comandos -- todas as flags e subcomandos de calendário