discord-cli Skill

CLI tool for Discord. fetch chat history, search messages, sync channels, AI analysis. use this when you need to pull message data from Discord servers, run AI-powered summaries, or keep a local searchable index of conversations.

intent

discord-cli is a Python CLI that connects to Discord via user token, pulls message history into local SQLite, and exposes YAML-first querying for AI agents. use it when you need machine-readable chat data, want to search across channels without hitting Discord's native search limits, or need to feed conversation context into Claude for analysis. the tool auto-handles rate limits and incremental syncs to keep your local database fresh.

inputs

environment & setup

• Python 3.10+ required
• install via uv tool install kabi-discord-cli or pipx install kabi-discord-cli
• Discord user token (not bot token) , auto-extracted and stored locally via discord auth --save
  • token stored at ~/.config/discord-cli/token (Linux/Mac) or equivalent on Windows
  • never shared or uploaded
• ANTHROPIC_API_KEY env var required for AI commands (analyze, summary)
• sqlite database at ~/Library/Application Support/discord-cli/messages.db on Mac, ~/.local/share/discord-cli/messages.db on Linux
• network connectivity to Discord API (api.discord.com)

command parameters

• <GUILD>: numeric Discord server ID
• <CHANNEL_ID>: numeric channel ID
• -n <int>: result limit (default varies by command, recommend -n 100-1000 for agents)
• -c <channel_name>: filter by channel name (search queries only)
• --hours <int>: time window in hours (default 24)
• -f json|yaml: output format override
• -o <file>: write output to file (avoids stdout buffering for large exports)
• --yaml: force YAML output (overrides TTY detection)
• -y: force confirm on destructive ops (purge)

external connections

• Discord API (rate limited to 50 requests per second per endpoint)
• Anthropic API (Claude) for analyze/summary commands (requires valid ANTHROPIC_API_KEY)

procedure

1. authenticate: run discord auth --save once. CLI auto-extracts token from Discord web session, validates connectivity via discord status, and stores locally. output: exit code 0 (valid) or 1 (invalid/expired).

2. discover servers & channels: run discord dc guilds --yaml to list all servers you're in. identify target guild ID. run discord dc channels <GUILD_ID> --yaml to list text channels. capture channel IDs you want to sync.

3. fetch initial history: for each channel, run discord dc history <CHANNEL_ID> -n 2000 --yaml. this pulls up to 2000 recent messages into local SQLite. output: YAML list of message objects (id, author, content, timestamp, attachments). edge case: if channel has >2000 messages, only recent 2000 are fetched on first run. to backfill older messages, re-run with same command (incremental logic respects last-stored timestamp).

4. incremental sync: run discord dc sync <CHANNEL_ID> or discord dc sync-all daily. compares last stored message timestamp to Discord API, fetches only new messages. output: count of new messages added. if no new messages, returns 0 (not an error).

5. query local database: run discord search "keyword" --yaml to find messages matching keyword in all channels. optionally filter by channel with -c <name>. output: YAML list of matching messages. edge case: empty result set returns empty YAML list [], not an error.

6. get structured context: run discord today --yaml to fetch all messages from last 24 hours. run discord top --hours 24 --yaml to rank most active senders. run discord stats --yaml for per-channel message counts. all output is YAML-formatted, suitable for piping to agent processing.

7. AI analysis (requires ANTHROPIC_API_KEY): run discord analyze <CHANNEL_ID> --hours 24 to feed last 24h of messages to Claude, get structured analysis (sentiment, topics, action items). output: YAML analysis object. run discord summary --hours 48 to get AI-generated summary of all messages in last 48h.

8. export data: run discord export <CHANNEL_ID> -f json -o /tmp/export.json to write all stored messages for a channel to file. useful for bulk processing or backup. output: JSON file written to disk, success message on stdout.

9. cleanup: run discord purge <CHANNEL_ID> -y to delete all stored messages for a channel from local SQLite. useful for privacy or disk management. output: confirmation message with message count deleted. edge case: purge is destructive, cannot be undone; -y flag required to skip interactive prompt.

10. live tail (optional): run discord dc tail <CHANNEL_ID> -n 20 to follow new messages in real-time as they arrive. blocks until interrupted (Ctrl-C). output: streaming YAML lines (one message per line). useful for monitoring active channels. edge case: tail stops if network drops; manually re-run to resume.

decision points

• if token is invalid or expired: discord status will exit code 1. re-run discord auth --save to refresh. if auto-extraction fails (e.g., Discord web not logged in), script prompts for manual token paste. always validate with discord status after saving.

• if ANTHROPIC_API_KEY is missing: analyze and summary commands will fail with explicit error. skip AI commands and use search/stats instead. if you have the key but Claude is rate-limited, wait 60 seconds and retry (exponential backoff is automatic).

• if a channel has no new messages since last sync: discord dc sync returns count 0. this is not an error. proceed with querying existing stored messages via search/stats/today commands.

• if search returns empty result set: command succeeds with exit code 0 and empty YAML list []. do not treat empty results as failure. refine query or expand time window with --hours.

• if SQLite database is corrupted or locked: commands fail with database error. delete the entire messages.db file and re-run discord dc history to rebuild. note: this loses all stored messages; backup first if you need it.

• if network timeout occurs: discord-cli automatically retries up to 3 times with exponential backoff. if all retries fail, command exits with network error. check your internet connection and re-run.

• if you hit Discord API rate limit: cli waits and retries automatically. if sync-all hits hard limit (429 error after retries), log the error and re-run sync-all in 15 minutes. rate limiting is per-endpoint, so querying different channels in parallel is safe.

• if output is for a TTY (interactive terminal): default format is rich (colored/formatted text). if output is piped or redirected (non-TTY), default is YAML. override with --yaml or OUTPUT=json env var.

• if exporting large channels (>100k messages): use -o <file> to write to disk instead of stdout. stdout buffering can cause memory spikes; file write is streamed.

output contract

all commands respect the OUTPUT env var and -f flag for format selection. default is yaml for non-TTY, rich for TTY. all structured outputs conform to schema documented in SCHEMA.md.

message object (YAML)

id: "1234567890"
guild_id: "9876543210"
channel_id: "5555555555"
author: "username#1234"
author_id: "1111111111"
content: "message text here"
timestamp: "2025-01-15T14:30:45.123Z"
edited_timestamp: null
attachments: []
reactions: ["👍", "❤️"]

search/query response (YAML list)

- id: "1234567890"
  author: "alice"
  content: "hello world"
  timestamp: "2025-01-15T14:30:45.123Z"
- id: "1234567891"
  author: "bob"
  content: "hello back"
  timestamp: "2025-01-15T14:31:10.456Z"

ai analysis response (YAML object)

channel: "general"
hours: 24
message_count: 42
sentiment: "positive"
topics: ["project-x", "onboarding", "bugs"]
action_items:
  - "fix bug #123"
  - "schedule meeting"
summary: "team discussed project-x progress and onboarding"

stats response (YAML object)

total_messages: 5000
by_channel:
  general: 2000
  random: 1500
  dev: 1500
by_sender:
  alice: 1200
  bob: 1000
  charlie: 800

export file (JSON, one message per line or single JSON array)

[
  {"id": "1234567890", "author": "alice", "content": "...", "timestamp": "..."},
  {"id": "1234567891", "author": "bob", "content": "...", "timestamp": "..."}
]

files are written to the path specified by -o <file>. exit code 0 on success, 1 on failure.

outcome signal

• discord status exits 0: token is valid and connected.
• discord dc guilds --yaml returns non-empty YAML list: you can see your servers.
• discord dc history <CHANNEL> -n 100 populates local SQLite and outputs 100 message objects: initial sync succeeded.
• discord search "keyword" --yaml returns YAML list (non-empty or empty): local query works.
• `