# コマンドラインインターフェース

ターミナルやスクリプト、CI からプッシュ通知を送信し、[Pocket Alert](https://pocketalert.app) のアプリケーション、デバイス、Webhook、API キーを管理できます。ソースコードとリリースは [github.com/PocketAlert/cli](https://github.com/PocketAlert/cli) で公開しています。

## インストール

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

スクリプトは SHA-256 チェックサムを検証し、`/usr/local/bin`（または `~/.local/bin`）にインストールします。特定のバージョンに固定するには `POCKETALERT_VERSION=v2.1.0` を設定してください。

### 手動ダウンロード

以下のリンクは常に最新リリースを指します。

| プラットフォーム | アーキテクチャ | ダウンロード |
|----------|--------------|----------|
| 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
```

## 認証

[設定 → API キー](https://pocketalert.app/account/apikeys) で API キーを作成し、次を実行します。

```bash
pocketalert auth
```

非表示のプロンプトにキーを貼り付けてください。キーはシェルの履歴に残りません。CLI はキーを `~/.pocketalert/config.json` に保存する前に検証します。パイプで渡すこともできます: `echo "$KEY" | pocketalert auth`。

CI やコンテナでは `auth` を使わず、環境変数を設定してください。

| 変数 | 用途 |
|----------|---------|
| `POCKETALERT_API_KEY` | API キー。保存済みのキーより優先されます |
| `POCKETALERT_API_URL` | API のベース URL（デフォルトは `https://api.pocketalert.app`） |
| `POCKETALERT_CONFIG` | 設定ファイルのパス |

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

---

## 通知の送信

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

タイトルとメッセージは引数またはフラグ（`-t`、`-m`）で指定できます。テキストをパイプで渡すか `-m -` を指定すると、標準入力からメッセージを読み込みます。

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

| フラグ | 説明 |
|------|-------------|
| `-a, --app <tid>` | アプリケーション |
| `-d, --device <tid>` | デバイス。`all` を指定するとすべてのデバイス（デフォルト） |
| `-l, --level <level>` | `silent`、`low`、`default`、`high`、`critical`（または `-2`…`2`） |
| `--action <type:label:value>` | アクションボタン。最大 3 回まで繰り返し指定可能 |
| `--image <path\|url>` | 画像の添付 |
| `--at <time>` | `2026-10-20 09:00`（アカウントのタイムゾーン）、RFC 3339、または Unix 秒で指定した日時に配信 |
| `--in <delay>` | `30m`、`2h`、`1d`、`1d12h` の経過後に配信 |
| `-q, --quiet` | メッセージの TID のみを出力 |

### 優先度

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

`critical` はおやすみモードを無視します。 (Paid) 無料プランでは `high` として配信され、CLI が注意メッセージを表示します。詳しくは [優先度](https://info.pocketalert.app/features/priority-levels.md) をご覧ください。

### アクションボタン (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"
```

| 種類 | 値 |
|------|-------|
| `view` | 開く URL |
| `http` | `URL`（POST を送信）、`GET https://…`、または JSON オブジェクト `{"url":"…","method":"PUT","headers":{…},"body":"…"}` |
| `copy` | コピーするテキスト |

詳しくは [アクションボタン](https://info.pocketalert.app/features/action-buttons.md) をご覧ください。

### 予約送信 (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>
```

メッセージは最大 30 日先まで予約できます。詳しくは [予約送信](https://info.pocketalert.app/features/scheduled-delivery.md) をご覧ください。

### 画像 (Paid)

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

---

## インタラクティブモード

```bash
pocketalert ui
```

`pocketalert ui` で全画面のアプリが開きます。受信トレイの閲覧と検索、メッセージの閲覧（開くと既読になります）、アプリケーション、デバイス、レベル、配信時刻、画像、アクションボタンを指定した新規メッセージの作成ができます。予約メッセージ、アプリケーション、デバイス、Webhook（最近のリクエストを含む）は 1 キーで開けます。新しいメッセージは自動で表示されます。

![プレビューウィンドウ付きの受信トレイ](https://info.pocketalert.app/images/cli/inbox.png)

プレビューウィンドウには、アクションボタンとそれぞれの移動先を含むメッセージ全体が表示されます。

![アクションボタン付きのメッセージ](https://info.pocketalert.app/images/cli/actions.png)

`n` で作成画面を開きます。アクションボタンには `type:label:value` と同じ `--action` 形式を使います。

![新規メッセージの作成](https://info.pocketalert.app/images/cli/compose.png)

| キー | 操作 |
|-----|--------|
| `tab`、`1`…`5` | 受信トレイ、予約、アプリケーション、デバイス、Webhook |
| `enter` / `esc` | 開く / 戻る。アプリケーションまたはデバイス上では、そのメッセージを表示 |
| `n` | 新規メッセージ。`ctrl+s` で送信 |
| `f` | 選択中のメッセージを再送または複製 |
| `r` / `a` / `u` | 既読の切り替え / すべて既読 / 未読のみ表示 |
| `d` | メッセージの削除、予約のキャンセル、リソースの削除（確認あり） |
| `s` | 選択中のアプリケーションまたはデバイスに送信 |
| `e` / `v` / `t` | 名前の変更 / アプリのデフォルトレベル / Webhook の一時停止または再開 |
| `/` | 検索 |
| `y` | メッセージ本文、TID、または Webhook URL をコピー |
| `?` | すべてのショートカットを表示 |

---

## コマンドの完了を通知

`exec` はコマンドを実行し、通常どおり出力をストリーミングしたあと、終了ステータス、所要時間、出力の末尾数行を含むプッシュ通知を送信します。コマンドの終了コードはそのまま引き継がれます。

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

| フラグ | 説明 |
|------|-------------|
| `--on <when>` | `always`（デフォルト）、`success`、`failure` |
| `--tail <n>` | 含める出力の行数（デフォルトは 10、`0` で省略） |
| `-t, --title <name>` | コマンド名の代わりにタイトルに表示する名前 |

失敗した実行のデフォルトレベルは `high` です。`send` の配信用フラグ（`-a`、`-d`、`-l`、`--action`、`--image`、`-q`）もここで使えます。確認メッセージは標準エラー出力に出るため、パイプ用にコマンドの標準出力はきれいに保たれます。

## ログの監視

`watch` はパイプで受け取った行を通知に変換します。`--batch`（デフォルトは `5s`）以内に届いた行は 1 通のプッシュにまとめられ、`--max-lines`（デフォルトは 20）まで含まれます。そのため、大量のエラーが出ても 1 日の上限の消費は 1 通分で済みます。`send` の配信用フラグもここで使えます。

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

---

## メッセージ

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

## アプリケーション

```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` は、レベルを指定しないメッセージに使うデフォルトのレベルを設定します。

## デバイス

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

## Webhook

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

出力には受信用 URL（`https://p4a.me/wh/…`）と、動作確認用の `curl` コマンドが表示されます。`webhooks update <tid>` は指定したフラグのみを変更します。Webhook を一時停止するには `--active=false` を使用してください。

## フォーム

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

フォームは [Web コンソール](https://pocketalert.app/forms) で作成します。

## API キー

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

> **Warning**
>
> トークンは作成時に一度だけ表示されます。すぐに保存してください。

---

## スクリプトでの利用

すべてのコマンドは `--json` を受け付け、API の生のレスポンスを出力します。

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

エラーは標準エラー出力に出力され、0 以外の終了コードで終了します。`429` レスポンスの場合は、1 日の上限と、そのリセット時刻が表示されます。

## 設定

```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`（パーミッションは `600`、ディレクトリは `700`）:

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

## 1.x からのアップグレード

上記のいずれかの方法で 2.x をインストールしてください。同じ `~/.pocketalert/config.json` を読み込むため、保存済みのキーはそのまま使えます。スクリプトには次の 3 点の変更が必要になる場合があります。

- **メッセージが必須になりました。** `pocketalert send -t "Cron OK"` を指定せずに `-m` を実行するとエラーになります。メッセージを指定するか、パイプで渡すか、`exec` を使用してください。
- **書式を混在させないでください。** `send "Title" "Message"` または `send -t "Title" -m "Message"` を使用してください。`send -t "Title" "Message"` は `title given both as argument and --title` というエラーで失敗します。
- **生成されたテキストには `-m` を使用してください。** `-` で始まる位置引数のメッセージ（例: AI エージェントが生成した Markdown のリスト）はフラグとして解析されます。`-m "$text"` を使えば常に安全です。

リリースのアーカイブは、古い `pocketalert_<os>_<arch>.tar.gz` ファイルの代わりに `.zip`（Windows では `cdn.pocketalert.app/cli/*.zip`）になりました。

## シェル補完

**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 を使う場合は、補完が自動でインストールされます。

---

## 例

### GitHub Actions

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

すぐに使えるステップを希望する場合は、[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
```

### サービスの死活監視

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