# 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](https://pocketalert.app). Código-fonte e releases: [github.com/PocketAlert/cli](https://github.com/PocketAlert/cli).

## Instalação

**Script (macOS/Linux)**

```bash
curl -fsSL https://raw.githubusercontent.com/PocketAlert/cli/main/install.sh | sh
```

**Homebrew**

```bash
brew install pocketalert/tap/pocketalert
```

**Go**

```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:

| Plataforma | Arquitetura | Download |
|----------|--------------|----------|
| Linux | AMD64 | [pocketalert_linux_amd64.tar.gz](https://github.com/PocketAlert/cli/releases/latest/download/pocketalert_linux_amd64.tar.gz) |
| Linux | ARM64 | [pocketalert_linux_arm64.tar.gz](https://github.com/PocketAlert/cli/releases/latest/download/pocketalert_linux_arm64.tar.gz) |
| macOS | Intel | [pocketalert_darwin_amd64.tar.gz](https://github.com/PocketAlert/cli/releases/latest/download/pocketalert_darwin_amd64.tar.gz) |
| macOS | Apple Silicon | [pocketalert_darwin_arm64.tar.gz](https://github.com/PocketAlert/cli/releases/latest/download/pocketalert_darwin_arm64.tar.gz) |
| Windows | AMD64 | [pocketalert_windows_amd64.zip](https://github.com/PocketAlert/cli/releases/latest/download/pocketalert_windows_amd64.zip) |

**Linux/macOS**

```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
```

**Windows**

```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](https://pocketalert.app/account/apikeys) 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ável | Finalidade |
|----------|---------|
| `POCKETALERT_API_KEY` | Chave de API. Tem prioridade sobre a salva |
| `POCKETALERT_API_URL` | URL base da API (padrão `https://api.pocketalert.app`) |
| `POCKETALERT_CONFIG` | Caminho 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"
```

| Flag | Descriçã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, --quiet` | Imprime 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. (Paid) No plano gratuito, ele é entregue como `high` e a CLI exibe um aviso. Veja [Níveis de prioridade](https://info.pocketalert.app/features/priority-levels.md).

### Botões de ação (Paid)

```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"
```

| Tipo | Valor |
|------|-------|
| `view` | URL a ser aberta |
| `http` | `URL` (envia POST), `GET https://…`, ou um objeto JSON `{"url":"…","method":"PUT","headers":{…},"body":"…"}` |
| `copy` | Texto a ser copiado |

Veja [Botões de ação](https://info.pocketalert.app/features/action-buttons.md).

### Envio agendado (Paid)

```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](https://info.pocketalert.app/features/scheduled-delivery.md).

### Imagens (Paid)

```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](https://info.pocketalert.app/images/cli/inbox.png)

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](https://info.pocketalert.app/images/cli/actions.png)

`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](https://info.pocketalert.app/images/cli/compose.png)

| Tecla | Ação |
|-----|--------|
| `tab`, `1`…`5` | Caixa de entrada, Agendadas, Aplicativos, Dispositivos, Webhooks |
| `enter` / `esc` | Abrir / voltar. Em um aplicativo ou dispositivo: mostra as mensagens dele |
| `n` | Nova mensagem. `ctrl+s` envia |
| `f` | Reenviar ou duplicar a mensagem selecionada |
| `r` / `a` / `u` | Alternar lida / marcar todas como lidas / mostrar apenas não lidas |
| `d` | Excluir uma mensagem, cancelar uma agendada ou remover um recurso (pede confirmação) |
| `s` | Enviar para o aplicativo ou dispositivo selecionado |
| `e` / `v` / `t` | Renomear / nível padrão do aplicativo / pausar ou retomar um webhook |
| `/` | Pesquisar |
| `y` | Copiar 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
```

| Flag | Descriçã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>
```

**Full JSON payload**

```bash
pocketalert webhooks create -n "GitHub" -m "*"
```

**Extract fields**

```bash
pocketalert webhooks create -n "Deploy" -m "Deployed %repository.name% by %sender.login%"
```

**Level and actions**

```bash
pocketalert webhooks create -n "Alertmanager" -m "%alerts.0.annotations.summary%" -l critical \
  --action "view:Open:%externalURL%"
```

**Custom URL**

```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](https://pocketalert.app/forms).

## 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

**zsh**

```bash
pocketalert completion zsh > "${fpath[1]}/_pocketalert"
```

**bash**

```bash
pocketalert completion bash > /etc/bash_completion.d/pocketalert
```

**fish**

```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](https://github.com/PocketAlert/notification-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"
```
