discord — Your Discord, Driven From the Terminal

🚧 Active development — daily tested, not daily committed

This repo is under heavy daily use (automated digests, MCP integrations, agent workflows). If commit activity looks sparse, it's because the tool is stable for its current feature set — no open issues, no regressions, no need for churn. New features ship when real workflows surface a gap, not on a schedule. Check Releases for the latest binary.

A Discord CLI + MCP server that operates your user account — so it sees every server, group, and DM you belong to. No bot invitation required.
Built in Rust for AI agents and terminal-first humans: 77 commands, SQLite archive with FTS5 search, stealth-aware, and an MCP server that plugs straight into Claude Code.

⚠️ ToS / account-risk warning — Automating a user account violates Discord's Terms of Service and can result in account termination. Use only on accounts you control, with restraint: rate limits are built in, reads are bounded, and destructive actions require explicit --confirm. Admin operations (channel-*, role-*, emoji-*) are the highest-risk surface — channel deletion is irreversible and plainly visible. auth --qr uses Discord's login API (highest risk) — opt-in only, never automatic. See docs/ADMIN.md for the permission matrix and ToS risk table.

Installation

# macOS / Linux — one-liner (downloads prebuilt binary)
curl -fsSL "https://raw.githubusercontent.com/quangdang46/discord_cli/main/install.sh?$(date +%s)" | bash

# With PATH auto-update + self-test
curl -fsSL "https://raw.githubusercontent.com/quangdang46/discord_cli/main/install.sh?$(date +%s)" | bash -s -- --easy-mode --verify

# Pin a specific version
curl -fsSL "https://raw.githubusercontent.com/quangdang46/discord_cli/main/install.sh?$(date +%s)" | bash -s -- --version v0.1.0

# Windows PowerShell
irm "https://raw.githubusercontent.com/quangdang46/discord_cli/main/install.ps1" | iex

Prebuilt binaries are attached to every GitHub release (Linux x86_64/aarch64 musl, macOS x86_64/aarch64, Windows x86_64) with .sha256 checksums.

# From source (requires Rust 1.80+)
cargo install --path crates/discord-cli --locked
# or build the workspace binary
cargo build --release && cp target/release/discord /usr/local/bin/

The workspace uses a tokio_unstable cfg for discord-user-rs (see .cargo/config.toml); cargo build handles it.

🤖 Agent Quickstart (Robot Mode)

This tool is built for AI agents. Every command emits machine-readable JSON/JSONL — never a bare interactive UI.

# 1) Authenticate once (auto-detect from local Discord/browser, or paste)
discord auth --save

# 2) "What can I see?" — discovery
discord guilds --json
discord dms --json

# 3) Read a channel (the agent-facing read)
discord read "guide" -l 20 --json

# 4) Archive + search offline
discord sync-all -l 200
discord search "deploy" -n 50

# 5) Reply (gated — needs --confirm for new messages)
discord send "guide" --text "Deploy looks good" --reply 1087808713206804713

# 6) Or run the full MCP server
claude mcp add discord --env DISCORD_TOKEN=$DISCORD_TOKEN -- $(which discord) serve

Output contract

• stdout = data only (JSONL when piped, --json for a single envelope)
• stderr = diagnostics
• exit 0 = success, 2 = usage (missing --confirm), 3 = not found, 4 = forbidden
• Envelope: {"ok":true,"schema_version":"1","data":[...]} / {"ok":false,...,"error":{...}}

See AGENTS.md for the full agent playbook (summarize / explore / reply / watch).

TL;DR

The Problem

• Bots are blind. A Discord bot only sees channels it was invited to — you can't have an AI read your private DMs, your friends' server, or a channel you joined years ago.
• The app is manual. Opening Discord to read/search/reply is slow; scripting it means fighting a GUI.
• Self-botting is risky. Unofficial user-token tools often scrape aggressively and get accounts banned.

The Solution

discord reads and writes Discord as your own account — every guild, group, and DM you belong to — from the terminal, with the same browser-like fingerprint a real client would send (UA, X-Super-Properties, per-install device_id). It archives what you read into SQLite for instant offline search, and exposes everything to agents over both CLI and MCP.

discord guilds
discord read "general" -l 20
discord search "meeting notes"

Why discord?

How discord Compares

Quick Example

# Authenticate (auto-detect from your local Discord/Chrome session)
discord auth --save                 # → {"authenticated":true,"source":"Chrome"}

# Verify who you are
discord whoami --json               # id, username, global_name, mfa_enabled

# Explore — what servers and DMs do you belong to?
discord guilds --json               # every guild you've joined
discord dms --json                  # DM + group-DM channels, labeled

# Drill into a server's channels
discord channels "TDG" --json       # text/announcement/forum, sorted

# Read recent messages (agent-friendly)
discord read "guide" -l 10 --json   # message_id, author, timestamp, content

# Archive a channel for offline search
discord sync "guide" -l 500         # → {"messages_synced": N}
discord sync "guide" --follow       # backfill, then keep persisting new messages (gateway)
discord sync "guide" --follow --max-duration 3600   # bounded follow (cron-friendly)
discord search "release" -n 20      # FTS5 over the local SQLite archive
discord stats --json                # per-channel counts

# Act (gated)
discord send "guide" --text "hi" --confirm       # requires --confirm
discord send "guide" --text "re:" --reply <MSG_ID>  # reply is auto-approved
discord send "guide" --text "https://x.com/..." --suppress-embeds  # no link preview
discord send "guide" --text "@mods ping" --mention-roles 111 222    # role-mention allowlist
discord react "guide" <MSG_ID> "👍"

# Live follow a keyword
discord watch --keyword "incident" --jsonl

Commands

Auth & identity

Read

Act

Admin & moderation

Admin ops map 403 → exit 4. Full permission matrix + risk table: docs/ADMIN.md.

Archive & query (local SQLite + FTS5)

Live & AI

Architecture

crates/
  discord-core/   REST client, stealth (X-Super-Properties, launch_signature),
                  config, types, output envelope
  discord-auth/   token auto-detect (LevelDB scan), paste, keyring, device_id
  discord-db/     SQLite schema, FTS5 search, two-phase sync state
  discord-cli/    the `discord` binary + 77 commands
  discord-mcp/    MCP server (rmcp stdio) — 43 tools

Design principles

Stealth status: The CLI sends real-client browser headers, X-Super-Properties, a masked launch_signature, per-install device_id, and gateway is_fast_connect. TLS ClientHello (JA3) fingerprinting is not yet spoofed (uses rustls) — an optional future feature. --tls-chrome is reserved but returns "not implemented" (exit 2).
| Safety gating | --confirm / --dry-run never interactive |
| Local-first archive | Read once, query forever (SQLite + FTS5) |
| Bounded by design | Sync caps, rate-limit backoff, invisible presence |

Safety & Rate Limits

Troubleshooting

Limitations

• User-token automation violates Discord ToS — accounts can be banned. Use sparingly.
• guild-search is per-guild (Discord's native search has no global scope).
• sync stores text content; attachments/embeds are not downloaded (extendable).
• Gateway tail/watch require a live connection; --once fetches a bounded window.
• MCP send_message is intentionally not auto-approved in clients — agents must request approval.

FAQ

Q: Why user token instead of a bot?
A bot only sees channels it's invited to. A user token sees everything you belong to — that's the whole point of an account-level CLI for an agent.

Q: Will I get banned?
Automating a user account violates ToS and bans are possible. This tool is designed to reduce risk (real-client headers, bounded reads, invisible presence) but cannot eliminate it. Use on accounts you control.

Q: How do I get a token?
discord auth --save scans your local Discord/Chrome LevelDB. Or discord auth --paste and paste it from DevTools → Network → Authorization header.

Q: Where is my data stored?
SQLite at the platform data dir ($LOCALAPPDATA/discord-cli/ on Windows, ~/.local/share/discord-cli/ on Linux, ~/Library/Application Support/discord-cli/ on macOS). Override with DB_PATH.

Q: Can an AI agent use this?
Yes — that's the primary design. --json/JSONL everywhere, discord serve for MCP, and AGENTS.md documents the playbook.

Q: Does it work on Windows?
Yes — built and tested on Windows, macOS, and Linux. Single static binary, no CGO.

Q: How do I stop watch/tail?
Ctrl+C. They run until interrupted.

Development

cargo build          # debug
cargo test           # 109 unit/integration tests (no network required)
./scripts/e2e.sh     # real-token smoke (needs DISCORD_TOKEN)
./scripts/e2e_admin.sh  # admin/mod flow (needs DISCORD_TOKEN + administered server)

Repo layout: research clones in .tmp/ (source of truth for patterns), plan in COMPREHENSIVEPLANFORDISCORDCLI.md, task graph in .beads/.

Solves "I can't have an AI read my Discord" — by being the account, not a guest.