Ir para o conteúdo

Interface de linha de comando ​

Envie notificações push do seu terminal, de scripts e de CI, e gerencie aplicativos, dispositivos, webhooks e chaves de API do Pocket Alert. Código-fonte e releases: github.com/PocketAlert/cli.

Instalação ​

bash
curl -fsSL https://raw.githubusercontent.com/PocketAlert/cli/main/install.sh | sh
bash
brew install pocketalert/tap/pocketalert
bash
go install github.com/PocketAlert/cli/cmd/pocketalert@latest

O script verifica o checksum SHA-256 e instala em /usr/local/bin (ou ~/.local/bin). Defina POCKETALERT_VERSION=v2.1.0 para fixar uma versão.

Download manual ​

Estes links sempre apontam para a versão mais recente:

PlataformaArquiteturaDownload
LinuxAMD64pocketalert_linux_amd64.tar.gz
LinuxARM64pocketalert_linux_arm64.tar.gz
macOSIntelpocketalert_darwin_amd64.tar.gz
macOSApple Siliconpocketalert_darwin_arm64.tar.gz
WindowsAMD64pocketalert_windows_amd64.zip
bash
tar -xzf pocketalert_*.tar.gz
sudo mv pocketalert /usr/local/bin/
# macOS, if Gatekeeper blocks a browser download:
xattr -d com.apple.quarantine /usr/local/bin/pocketalert
powershell
# Unzip, then add the folder with pocketalert.exe to PATH
.\pocketalert.exe --help

Autenticação ​

Crie uma chave de API em Configurações → Chaves de API e depois execute:

bash
pocketalert auth

Cole a chave no prompt oculto. Ela não fica no histórico do seu shell. A CLI valida a chave antes de salvá-la em ~/.pocketalert/config.json. Você também pode passá-la por pipe: echo "$KEY" | pocketalert auth.

Em CI e containers, pule o auth e defina uma variável de ambiente:

VariávelFinalidade
POCKETALERT_API_KEYChave de API. Tem prioridade sobre a salva
POCKETALERT_API_URLURL base da API (padrão https://api.pocketalert.app)
POCKETALERT_CONFIGCaminho do arquivo de configuração
bash
pocketalert profile   # who am I?
pocketalert logout    # remove the saved key

Enviando notificações ​

bash
pocketalert send "Deploy finished" "v1.4.2 is live"

Título e mensagem podem ser argumentos ou flags (-t, -m). Use pipe para passar texto, ou -m -, para ler a mensagem da entrada padrão:

bash
df -h | pocketalert send "Disk report"
FlagDescrição
-a, --app <tid>Aplicativo
-d, --device <tid>Dispositivo, ou all (padrão: todos os dispositivos)
-l, --level <level>silent, low, default, high, critical (ou -2…2)
--action <type:label:value>Botão de ação, repetível até 3 vezes
--image <path|url>Anexo de imagem
--at <time>Entrega em 2026-10-20 09:00 (fuso horário da conta), RFC 3339 ou segundos Unix
--in <delay>Entrega após 30m, 2h, 1d, 1d12h
-q, --quietImprime apenas o TID da mensagem

Níveis ​

bash
pocketalert send "Disk 95%" "/var is almost full" --level high
pocketalert send "Prod is down" "502 from api" --level critical

critical ignora o modo Não perturbe. Pago No plano gratuito, ele é entregue como high e a CLI exibe um aviso. Veja Níveis de prioridade.

Botões de ação Pago ​

bash
pocketalert send "Deploy failed" "main@4f2c" -l critical \
  --action "view:Open logs:https://ci.example.com/run/1" \
  --action "http:Retry:https://ci.example.com/run/1/retry" \
  --action "copy:Copy SHA:4f2c9e1"
TipoValor
viewURL a ser aberta
httpURL (envia POST), GET https://…, ou um objeto JSON {"url":"…","method":"PUT","headers":{…},"body":"…"}
copyTexto a ser copiado

Veja Botões de ação.

Envio agendado Pago ​

bash
pocketalert send "Standup" "In 10 minutes" --at "2026-10-20 09:50"
pocketalert send "Reminder" "Rotate the keys" --in 1d

pocketalert scheduled list                  # pending, soonest first
pocketalert scheduled list --status all
pocketalert scheduled cancel <tid>

As mensagens podem ser agendadas com até 30 dias de antecedência. Veja Envio agendado.

Imagens Pago ​

bash
pocketalert send "Grafana" "CPU spike" --image ./panel.png
pocketalert send "Grafana" "CPU spike" --image https://example.com/panel.png

Modo interativo ​

bash
pocketalert ui

pocketalert ui abre um aplicativo em tela cheia. Navegue e pesquise na caixa de entrada, leia mensagens (abrir uma marca como lida) e componha novas mensagens com aplicativo, dispositivo, nível, horário de entrega, imagem e botões de ação. Mensagens agendadas, aplicativos, dispositivos e webhooks, com as requisições recentes, ficam a uma tecla de distância. Novas mensagens aparecem automaticamente.

Caixa de entrada com o painel de visualização

O painel de visualização mostra a mensagem completa, incluindo os botões de ação e para onde cada um aponta:

Uma mensagem com botões de ação

n abre o compositor. Os botões de ação usam o mesmo formato type:label:value da opção --action:

Compondo uma nova mensagem

TeclaAção
tab, 1…5Caixa de entrada, Agendadas, Aplicativos, Dispositivos, Webhooks
enter / escAbrir / voltar. Em um aplicativo ou dispositivo: mostra as mensagens dele
nNova mensagem. ctrl+s envia
fReenviar ou duplicar a mensagem selecionada
r / a / uAlternar lida / marcar todas como lidas / mostrar apenas não lidas
dExcluir uma mensagem, cancelar uma agendada ou remover um recurso (pede confirmação)
sEnviar para o aplicativo ou dispositivo selecionado
e / v / tRenomear / nível padrão do aplicativo / pausar ou retomar um webhook
/Pesquisar
yCopiar o texto da mensagem, o TID ou a URL do webhook
?Todos os atalhos

Seja notificado quando um comando terminar ​

exec executa um comando, transmite a saída normalmente e depois envia um push com o status de saída, a duração e as últimas linhas da saída. O código de saída do comando é repassado.

bash
pocketalert exec -- make release
pocketalert exec --on failure -l critical -- ./backup.sh
pocketalert exec -t "Nightly import" --tail 20 -- python import.py
FlagDescrição
--on <when>always (padrão), success, failure
--tail <n>Linhas da saída a incluir (padrão 10, 0 para omitir)
-t, --title <name>Nome no título, em vez do comando

Execuções com falha usam o nível high por padrão. As flags de entrega de send (-a, -d, -l, --action, --image, -q) também funcionam aqui. A confirmação vai para stderr, então a stdout do comando continua limpa para pipes.

Acompanhe um log ​

watch transforma linhas recebidas por pipe em notificações. As linhas que chegam dentro de --batch (padrão 5s) são agrupadas em um único push, até --max-lines (padrão 20). Assim, uma rajada de erros consome apenas uma mensagem da sua cota diária. As flags de entrega de send também funcionam aqui.

bash
tail -f app.log | grep --line-buffered ERROR | pocketalert watch -t "app errors"
journalctl -fu nginx | pocketalert watch --batch 1m -l high

Mensagens ​

bash
pocketalert messages list                 # 20 newest
pocketalert messages list -n 50 --offset 50
pocketalert messages list --sort asc --device <device-tid>
pocketalert messages get <tid>            # also marks it as read
pocketalert messages read <tid> [<tid>…]
pocketalert messages read --all
pocketalert messages delete <tid> [<tid>…]
pocketalert messages delete --all         # asks for confirmation; --yes in scripts
pocketalert messages stats                # messages per day
pocketalert usage                         # today's usage against the daily limit

Aplicativos ​

bash
pocketalert apps list
pocketalert apps get <tid>
pocketalert apps create -n "Production" -c "#EF4444" -l high
pocketalert apps update <tid> --name "Prod" --level critical
pocketalert apps delete <tid>

--level define o nível padrão para mensagens que não especificam um.

Dispositivos ​

bash
pocketalert devices list
pocketalert devices get <tid>
pocketalert devices rename <tid> "Work iPhone"
pocketalert devices delete <tid>

Webhooks ​

bash
pocketalert webhooks list
pocketalert webhooks get <tid>
pocketalert webhooks history <tid> [--status error] [--page 2]
pocketalert webhooks delete <tid>
bash
pocketalert webhooks create -n "GitHub" -m "*"
bash
pocketalert webhooks create -n "Deploy" -m "Deployed %repository.name% by %sender.login%"
bash
pocketalert webhooks create -n "Alertmanager" -m "%alerts.0.annotations.summary%" -l critical \
  --action "view:Open:%externalURL%"
bash
pocketalert webhooks create -n "Uptime" -m "%monitor.name% is %status%" --slug uptime-alerts

A saída mostra a URL de entrada (https://p4a.me/wh/…) e um comando curl para testá-la. webhooks update <tid> altera apenas as flags que você passar. Use --active=false para pausar um webhook.

Formulários ​

bash
pocketalert forms list
pocketalert forms delete <tid>

Os formulários são criados no console web.

Chaves de API ​

bash
pocketalert apikeys list
pocketalert apikeys create -n "CI"
pocketalert apikeys delete <tid>

WARNING

O token é exibido uma única vez, na criação. Guarde-o imediatamente.


Scripts ​

Todos os comandos aceitam --json e exibem a resposta bruta da API:

bash
pocketalert messages list --json | jq -r '.data[].title'
TID=$(pocketalert send "Build" "started" -q)

Erros vão para stderr e encerram com código de saída diferente de zero. Uma resposta 429 explica o limite diário e quando ele será reiniciado.

Configuração ​

bash
pocketalert config                                    # show settings and where the key comes from
pocketalert config set base_url https://api.example.com
pocketalert config reset base_url

~/.pocketalert/config.json (permissões 600, diretório 700):

json
{
  "api_key": "your-api-key",
  "base_url": "https://api.pocketalert.app"
}

Atualizando da 1.x ​

Instale a 2.x com qualquer um dos métodos acima. Ela lê o mesmo ~/.pocketalert/config.json, então a chave salva continua funcionando. Os scripts podem precisar de três ajustes:

  • Uma mensagem é obrigatória. pocketalert send -t "Cron OK" sem -m agora gera erro. Adicione uma mensagem, passe uma por pipe ou use exec.
  • Não misture as formas. Use send "Title" "Message" ou send -t "Title" -m "Message". send -t "Title" "Message" falha com title given both as argument and --title.
  • Use -m para texto gerado. Uma mensagem posicional que começa com - (uma lista Markdown gerada por um agente de IA, por exemplo) é interpretada como flag. -m "$text" é sempre seguro.

Os arquivos de release agora são pocketalert_<os>_<arch>.tar.gz (.zip no Windows), em vez dos antigos arquivos cdn.pocketalert.app/cli/*.zip.

Autocompletar no shell ​

bash
pocketalert completion zsh > "${fpath[1]}/_pocketalert"
bash
pocketalert completion bash > /etc/bash_completion.d/pocketalert
bash
pocketalert completion fish > ~/.config/fish/completions/pocketalert.fish

O Homebrew instala os autocompletares automaticamente.


Exemplos ​

GitHub Actions ​

yaml
- name: Deploy
  run: pocketalert exec -t "Deploy ${{ github.ref_name }}" -- make deploy
  env:
    POCKETALERT_API_KEY: ${{ secrets.POCKETALERT_API_KEY }}

Prefere um step pronto? Veja a GitHub Action.

Cron ​

bash
# Alert only when the backup fails
0 3 * * * /usr/local/bin/pocketalert exec --on failure -l critical -- /opt/backup.sh

Verificação de serviço ​

bash
#!/bin/sh
systemctl is-active --quiet nginx || \
  pocketalert send "NGINX down" "on $(hostname)" -l critical \
    --action "view:Status page:https://status.example.com"

Documentação do Pocket Alert