# Interfaz de línea de comandos

Envía notificaciones push desde tu terminal, tus scripts y tu CI, y gestiona las aplicaciones, dispositivos, webhooks y claves de API de [Pocket Alert](https://pocketalert.app). Código fuente y versiones: [github.com/PocketAlert/cli](https://github.com/PocketAlert/cli).

## Instalación

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

El script verifica la suma de comprobación SHA-256 e instala en `/usr/local/bin` (o `~/.local/bin`). Define `POCKETALERT_VERSION=v2.1.0` para fijar una versión.

### Descarga manual

Estos enlaces siempre apuntan a la última versión:

| Plataforma | Arquitectura | Descarga |
|----------|--------------|----------|
| 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
```

## Autenticación

Crea una clave de API en [Configuración → Claves de API](https://pocketalert.app/account/apikeys) y, después, ejecuta:

```bash
pocketalert auth
```

Pega la clave en el aviso oculto: no se guarda en el historial de tu shell. La CLI comprueba la clave antes de guardarla en `~/.pocketalert/config.json`. También puedes pasarla por una tubería: `echo "$KEY" | pocketalert auth`.

En CI y contenedores, omite `auth` y define una variable de entorno:

| Variable | Función |
|----------|---------|
| `POCKETALERT_API_KEY` | Clave de API; tiene prioridad sobre la guardada |
| `POCKETALERT_API_URL` | URL base de la API (por defecto `https://api.pocketalert.app`) |
| `POCKETALERT_CONFIG` | Ruta del archivo de configuración |

```bash
pocketalert profile   # who am I?
pocketalert logout    # remove the saved key
```

---

## Enviar notificaciones

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

El título y el mensaje pueden ser argumentos o flags (`-t`, `-m`). Envía texto por una tubería, o usa `-m -`, para leer el mensaje desde la entrada estándar:

```bash
df -h | pocketalert send "Disk report"
```

| Flag | Descripción |
|------|-------------|
| `-a, --app <tid>` | Aplicación |
| `-d, --device <tid>` | Dispositivo, o `all` (por defecto: todos los dispositivos) |
| `-l, --level <level>` | `silent`, `low`, `default`, `high`, `critical` (o `-2`…`2`) |
| `--action <type:label:value>` | Botón de acción, repetible hasta 3 veces |
| `--image <path\|url>` | Imagen adjunta |
| `--at <time>` | Entrega en `2026-10-20 09:00` (zona horaria de la cuenta), RFC 3339 o segundos Unix |
| `--in <delay>` | Entrega tras `30m`, `2h`, `1d`, `1d12h` |
| `-q, --quiet` | Muestra solo el TID del mensaje |

### Niveles

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

`critical` omite No molestar. (Paid) En el plan gratuito se entrega como `high` y la CLI muestra un aviso. Consulta [Niveles de prioridad](https://info.pocketalert.app/features/priority-levels.md).

### Botones de acción (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 que se abre |
| `http` | `URL` (envía POST), `GET https://…`, o un objeto JSON `{"url":"…","method":"PUT","headers":{…},"body":"…"}` |
| `copy` | Texto que se copia |

Consulta [Botones de acción](https://info.pocketalert.app/features/action-buttons.md).

### Envío programado (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>
```

Los mensajes se pueden programar con hasta 30 días de antelación. Consulta [Envío programado](https://info.pocketalert.app/features/scheduled-delivery.md).

### Imágenes (Paid)

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

---

## Modo interactivo

```bash
pocketalert ui
```

`pocketalert ui` abre una aplicación a pantalla completa. Navega y busca en la bandeja de entrada, lee mensajes (al abrir uno se marca como leído) y redacta mensajes nuevos con una aplicación, un dispositivo, un nivel, una hora de entrega, una imagen y botones de acción. Los mensajes programados, las aplicaciones, los dispositivos y los webhooks, junto con sus solicitudes recientes, están a una sola pulsación. Los mensajes nuevos aparecen automáticamente.

![Bandeja de entrada con el panel de vista previa](https://info.pocketalert.app/images/cli/inbox.png)

El panel de vista previa muestra el mensaje completo, incluidos sus botones de acción y el destino de cada uno:

![Un mensaje con botones de acción](https://info.pocketalert.app/images/cli/actions.png)

`n` abre el redactor. Los botones de acción usan el mismo formato `type:label:value` que `--action`:

![Redactando un mensaje nuevo](https://info.pocketalert.app/images/cli/compose.png)

| Tecla | Acción |
|-----|--------|
| `tab`, `1`…`5` | Bandeja de entrada, Programados, Aplicaciones, Dispositivos, Webhooks |
| `enter` / `esc` | Abrir / volver. En una aplicación o dispositivo: muestra sus mensajes |
| `n` | Mensaje nuevo; `ctrl+s` lo envía |
| `f` | Reenviar o duplicar el mensaje seleccionado |
| `r` / `a` / `u` | Alternar leído / marcar todos como leídos / mostrar solo no leídos |
| `d` | Eliminar un mensaje, cancelar uno programado o quitar un recurso (pide confirmación) |
| `s` | Enviar a la aplicación o dispositivo seleccionado |
| `e` / `v` / `t` | Renombrar / nivel predeterminado de la aplicación / pausar o reanudar un webhook |
| `/` | Buscar |
| `y` | Copiar el texto del mensaje, el TID o la URL del webhook |
| `?` | Todos los atajos |

---

## Notificar cuando termina un comando

`exec` ejecuta un comando, muestra su salida como de costumbre y después envía una push con el estado de salida, la duración y las últimas líneas de la salida. Se conserva el código de salida del comando.

```bash
pocketalert exec -- make release
pocketalert exec --on failure -l critical -- ./backup.sh
pocketalert exec -t "Nightly import" --tail 20 -- python import.py
```

| Flag | Descripción |
|------|-------------|
| `--on <when>` | `always` (por defecto), `success`, `failure` |
| `--tail <n>` | Líneas de salida que se incluyen (por defecto 10, `0` para omitirlas) |
| `-t, --title <name>` | Nombre en el título en lugar del comando |

Las ejecuciones fallidas usan por defecto el nivel `high`. Los flags de entrega de `send` (`-a`, `-d`, `-l`, `--action`, `--image`, `-q`) también funcionan aquí. La confirmación se envía a stderr, así que la salida estándar del comando queda limpia para las tuberías.

## Vigilar un log

`watch` convierte las líneas recibidas por tubería en notificaciones. Las líneas que llegan dentro de `--batch` (por defecto `5s`) se agrupan en una sola push, hasta `--max-lines` (por defecto 20), de modo que una ráfaga de errores consume un solo mensaje de tu límite diario. Los flags de entrega de `send` también funcionan aquí.

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

---

## Mensajes

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

## Aplicaciones

```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 el nivel predeterminado para los mensajes que no especifiquen uno.

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

La salida muestra la URL de entrada (`https://p4a.me/wh/…`) y un comando `curl` para probarla. `webhooks update <tid>` cambia solo los flags que indiques; usa `--active=false` para pausar un webhook.

## Formularios

```bash
pocketalert forms list
pocketalert forms delete <tid>
```

Los formularios se crean en la [consola web](https://pocketalert.app/forms).

## Claves de API

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

> **Warning**
>
> El token se muestra una sola vez al crearlo: guárdalo enseguida.

---

## Scripting

Todos los comandos aceptan `--json` y muestran la respuesta de la API sin procesar:

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

Los errores se envían a stderr y终 salen con un código distinto de cero. Una respuesta `429` explica el límite diario y cuándo se restablece.

## Configuración

```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` (permisos `600`, directorio `700`):

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

## Migrar desde la 1.x

Instala la 2.x con cualquiera de los métodos anteriores; lee el mismo `~/.pocketalert/config.json`, así que la clave guardada sigue funcionando. Es posible que los scripts necesiten tres cambios:

- **El mensaje es obligatorio.** `pocketalert send -t "Cron OK"` sin `-m` ya es un error. Añade un mensaje, envíalo por una tubería o usa `exec`.
- **No mezcles las formas.** Usa `send "Title" "Message"` o `send -t "Title" -m "Message"`. `send -t "Title" "Message"` falla con `title given both as argument and --title`.
- **Usa `-m` para texto generado.** Un mensaje posicional que empiece por `-` (por ejemplo, una lista Markdown de un agente de IA) se interpreta como flag; `-m "$text"` siempre es seguro.

Los archivos de versión ahora son `pocketalert_<os>_<arch>.tar.gz` (`.zip` en Windows) en lugar de los antiguos archivos `cdn.pocketalert.app/cli/*.zip`.

## Autocompletado de 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
```

Homebrew instala los autocompletados automáticamente.

---

## Ejemplos

### GitHub Actions

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

¿Prefieres un paso ya hecho? Consulta la [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
```

### Comprobación de servicio

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