Skip to main content

Discord Message CLI (discord-msg)

権限を持つ Discord チャンネルのメッセージを Discord 公式 HTTP API (v10) で取得・期間別集計・投稿する CLI ツールです。
人がターミナルで表を確認するほか、AI エージェントやスクリプトが JSON 形式で安全に集計・投稿結果のメタデータだけを取得できるように設計されています。

特徴とセキュリティ方針

  • 最小権限の API 操作: メッセージ履歴の取得(GET /channels/{channel_id}/messages)とメッセージ投稿(POST /channels/{channel_id}/messages)のみを行い、削除や権限変更の機能は持ちません。また HTTP リダイレクトの自動追従を無効化し、トークンの外部漏えいを防ぎます。
  • メンションは既定で無効: send コマンドによる投稿時は、デフォルトで allowed_mentions: {"parse": []} を送信し、本文中に @everyone・@here・ユーザー/ロールメンションが含まれていても通知が飛ばない安全設計です(明示的に --allow-mentions を指定した場合のみ有効化)。
  • 本文・添付の非出力: 接続確認(check)・期間集計(stats)・メッセージ投稿(send)の出力(表・JSON ともに)には、メッセージ本文・添付ファイル・トークンを一切含めません。
  • 安全なトークン入力: Bot トークンは環境変数(DISCORD_BOT_TOKEN)、対話的な非表示入力(--prompt-token)、または標準入力(--token-stdin)からのみ受け付けます。コマンドライン引数や設定ファイルには保存・指定できません。
  • 標準出力と標準エラーの分離: 診断メッセージやエラーはすべて標準エラー(stderr)に出力され、標準出力(stdout)には完全な結果(表または JSON)のみが出力されます。取得途中で失敗した場合は、不完全な集計を標準出力に出さず非ゼロ終了コードで終了します。

導入方法

Python 3.10 以上が必要です。pipx または pip でワンコマンド導入できます。

# PyPI から導入する場合(推奨)
pipx install discord-message-cli
# または
pip install discord-message-cli

# GitHub リポジトリから直接導入する場合
pipx install git+https://github.com/IT-Engineer-K/discord-message-cli.git

# ローカルのクローンから導入する場合
pipx install .

認証設定

実行前に環境変数 DISCORD_BOT_TOKEN を設定するか、実行時に --prompt-token を指定してください。

# PowerShell で一時的に環境変数へ設定する例
$env:DISCORD_BOT_TOKEN = (Read-Host -AsSecureString "Bot Token" | ConvertFrom-SecureString -AsPlainText)

必要な Discord Bot 権限: 対象チャンネルに対する View Channel(チャンネルを見る)、Read Message History(メッセージ履歴を読む・check/stats 用)、および Send Messages(メッセージを送信・send 用)。
※ 接頭辞(--prefix)やキーワード(--keyword)による本文絞り込みを行う場合は、Discord Developer Portal で Bot の Message Content Intent を有効にしてください。

使い方

1. 接続確認 (check)

対象チャンネルの履歴を読み取れるかを確認し、本文を表示せずに結果を返します。

# 表形式(既定)
discord-msg check --channel 123456789012345678

# AI / スクリプト向け JSON 形式
discord-msg check --channel 123456789012345678 --format json

# トークンを対話的非表示入力で渡す場合
discord-msg check --channel 123456789012345678 --prompt-token

JSON 出力例:

{
  "ok": true,
  "channel_id": "123456789012345678",
  "reachable": true,
  "history_readable": true,
  "has_messages": true
}

2. 期間別集計 (stats)

指定期間のメッセージ件数を集計します。

  • 既定期間: 直近 24 時間(--since / --until / --hours で変更可能。開始時刻を含み、終了時刻は含まない [start, end))
  • 既定タイムゾーン: 日本時間 Asia/Tokyo(--tz で変更可能)
  • 集計単位 (--by): hour(時間別・既定)、day(日別)、total(合計のみ)
  • 絞り込み: --prefix(本文の接頭辞)、--keyword(本文に含まれるキーワード)、--ignore-case(大文字・小文字を区別しない)
# 直近24時間の時間別集計(日本時間・表形式)
discord-msg stats --channel 123456789012345678

# 期間と接頭辞・キーワードを指定して AI 向け JSON で取得
discord-msg stats `
  --channel 123456789012345678 `
  --since 2026-11-18T00:00:00+09:00 `
  --until 2026-11-19T00:00:00+09:00 `
  --by hour `
  --prefix "[ALERT]" `
  --keyword "DiskHigh" `
  --format json

JSON 出力例:

{
  "channel_id": "123456789012345678",
  "period": {
    "start": "2026-11-18T09:00:00+09:00",
    "end": "2026-11-18T12:00:00+09:00"
  },
  "timezone": "Asia/Tokyo",
  "granularity": "hour",
  "filter": {
    "prefix": "[ALERT]",
    "keyword": "DiskHigh",
    "ignore_case": false
  },
  "buckets": [
    {
      "label": "2026-11-18 09:00",
      "start": "2026-11-18T09:00:00+09:00",
      "end": "2026-11-18T10:00:00+09:00",
      "count": 2
    },
    {
      "label": "2026-11-18 10:00",
      "start": "2026-11-18T10:00:00+09:00",
      "end": "2026-11-18T11:00:00+09:00",
      "count": 0
    },
    {
      "label": "2026-11-18 11:00",
      "start": "2026-11-18T11:00:00+09:00",
      "end": "2026-11-18T12:00:00+09:00",
      "count": 3
    }
  ],
  "total": 5,
  "scanned_in_period": 8
}

3. メッセージ投稿 (send)

指定チャンネルにメッセージを投稿します。デフォルトではすべてのメンション(@everyone / @here / ユーザー / ロール)が無効化されます。

# 位置引数または --message (-m) で投稿(メンションはデフォルト禁止)
discord-msg send --channel 123456789012345678 "バッチ処理が完了しました"
discord-msg send --channel 123456789012345678 -m "バッチ処理が完了しました" --format json

# 標準入力から本文を渡して投稿
"複数行のメッセージ" | discord-msg send --channel 123456789012345678 --stdin

# メンションを明示的に許可する場合のみ --allow-mentions を指定
discord-msg send --channel 123456789012345678 "@here 緊急アラート" --allow-mentions

JSON 出力例:

{
  "ok": true,
  "channel_id": "123456789012345678",
  "message_id": "1308123456789012345",
  "timestamp": "2026-11-19T04:55:00.000000+00:00",
  "mentions_allowed": false
}

ローカル設定ファイル(任意・非機密値のみ)

毎回 --channel を指定する代わりに、環境変数 DISCORD_CHANNEL_ID またはローカル設定ファイル(Windows の既定パス: %APPDATA%\discord-msg\config.json)に既定のチャンネル ID とタイムゾーンを記述できます。
※ セキュリティ保護のため、設定ファイルに token / bot_token キーが含まれている場合はエラーとして拒否します。

{
  "channel": "123456789012345678",
  "tz": "Asia/Tokyo"
}

終了コード一覧

終了コード エラーコード 意味
0 - 正常終了(履歴が空の場合も含む)
2 INVALID_ARGS 引数・期間指定・設定ファイルの形式エラー
3 AUTH_FAILED トークン未指定または認証失敗 (401 Unauthorized)
4 PERMISSION_DENIED チャンネル閲覧・履歴読み取り権限不足 (403 Forbidden)
5 NOT_FOUND チャンネルが存在しないかアクセス不可 (404 Not Found)
6 RATE_LIMITED レート制限の再試行上限超過 (429 Too Many Requests)
7 FETCH_FAILED 通信エラーやページ送り途中の API エラー(不完全な集計は返さない)

テストの実行

テストにはすべて架空のチャンネル ID・架空の通知データを使用しており、外部通信を行わずに実行できます。

$env:PYTHONPATH="src"
python -m unittest discover -s tests -v

Metadata

Release files for discord-message-cli 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for discord-message-cli 0.2.0
File Size Uploaded Provenance Actions
discord_message_cli-0.2.0.tar.gz 22.2 kB With provenance Details for discord_message_cli-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for discord-message-cli 0.2.0
File Interpreter ABI Platform Actions
discord_message_cli-0.2.0-py3-none-any.whl Python 3 none any Details for discord_message_cli-0.2.0-py3-none-any.whl

Total release size: 42.0 kB

Release files / discord_message_cli-0.2.0.tar.gz

Download URL discord_message_cli-0.2.0.tar.gz
Size 22.2 kB
Tags Source
SHA-256 checksum
How to use checksums
72e64dd29b086c5b3e02556e71c861949fe335dcd6aec9c32d560f4b4ebde926
BLAKE2b-256 checksum
How to use checksums
98b99a1bc5d27da80af1a620f535ba1f45e26f41c4b7f4d0e5b9f6e52aa4d43d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / discord_message_cli-0.2.0-py3-none-any.whl

Download URL discord_message_cli-0.2.0-py3-none-any.whl
Size 19.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1c7ceafde02f50019d6b52ab0b4208fdd26b16d050ba414ed19c3349376d69a6
BLAKE2b-256 checksum
How to use checksums
0dc150b6ee609dce38b69171ad6706f083e087b7c99a476a32d2ec7fdbae4812
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for discord-message-cli 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for discord_message_cli-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page