discrawl: local Discord history you can actually search

What the tool is for

Discrawl archives Discord guild data and classifiable Discord Desktop cache messages in local SQLite for offline search, SQL and terminal browsing. The README states the audience plainly: people who need durable server history, local recovery of cached direct messages, or read-only access to a shared archive. The tagline says it in fewer words, Discord history without the scroll. The important architectural point is that the archive is local and queryable, not a live client. Once the data is in SQLite you own it, you can search it with full text search built into the database, and you can run read-only SQL over it for analysis. That is the difference from scrolling, and it is the reason the tool is worth the setup.

Installing it

Homebrew is the smallest path on macOS and Linux.

brew install openclaw/tap/discrawl
discrawl --version

Windows binaries and signed archives for all supported platforms are available from GitHub Releases. The published macOS CLI targets macOS 13.0, and CI checks that minimum explicitly. To build from source you need Go 1.27.0 or newer, with the module selecting Go 1.27.2 as its preferred toolchain.

git clone https://github.com/openclaw/discrawl.git
cd discrawl
go build -o bin/discrawl ./cmd/discrawl
./bin/discrawl --version

The installation guide covers Docker, runtime paths and update checks. The repository has a Dockerfile alongside the Makefile, and the module requires Go 1.27.0 with the toolchain directive naming go1.27.2.

Four archive sources with very different trust models

The source table is the part of the documentation that deserves the most attention, because the four routes have different setup and different consequences. A Discord bot, configured by you, gives guilds, channels, threads, members and bot-visible message history. The Discord Desktop cache gives locally cached guild messages and classifiable direct messages. A Git snapshot gives offline, token-free access to an archive published by another machine. A remote archive gives read-only access through a configured Worker without local SQLite. The first requires credentials, the second requires no credentials at all, and the third and fourth require somebody else to have published something. The bot-backed route is the setup the README walks through.

export DISCORD_BOT_TOKEN="your-bot-token"
discrawl init
discrawl doctor
discrawl sync

The sync command collects recent data by default, and sync --full does a historical backfill, which can take time because Discord rate-limits history requests.

The wiretap mode and what it deliberately does not do

The wiretap command inspects the local Discord Desktop cache, and you can run it with a dry run and JSON output before anything is imported.

discrawl wiretap --dry-run --json

The README is explicit about the boundary: wiretap imports only messages already cached by Discord Desktop, and it is not a complete account-history fetch. Direct messages stay local and are excluded from shared snapshots. The security section repeats it from the other direction: wiretap reads local cache files only, it does not extract a user token, it does not call Discord as the user, and it does not run a selfbot. That last set of sentences is what makes the mode acceptable, because the obvious abuse of a cache-reading tool is exactly the one it rules out. The separate search command for direct messages exists as a flag rather than as a mode that requires a different trust decision.

Search that works without a service

Full text search using FTS5 works without external services.

discrawl search "panic: nil pointer"
discrawl search --channel general --author steipete "release"
discrawl messages --channel general --hours 24
discrawl tui

There are structured browsing commands for direct messages, mentions, members and channels, and a sql command that exposes read-only queries for analysis. Semantic and hybrid search are optional: they require an embedding provider and an explicit indexing pass, with full text search remaining the default. There is a separate guide on search modes and another on embeddings, plus a multilingual lexical benchmark in the documentation set, which suggests the team has thought about the case where the query and the message are in different languages, since that is where a lexical index quietly fails.

Sharing an archive without sharing credentials

The publish command writes a sharded Git snapshot that another machine can consume with the subscribe command, and readers need access to the snapshot repository but do not need Discord credentials.

discrawl publish --check
discrawl publish

The preflight is read-only and reports the export scope before any snapshot is written. Published snapshots exclude wiretap direct messages and local failure history. There is a subtle detail in how readers consume them: dedicated readers of privacy-filtered snapshots can subscribe with an exact flag so later omissions remove previously shared rows, while normal subscriptions preserve richer local rows. In other words, a snapshot that has been filtered for privacy can be revised later to remove something, and a reader who subscribed in the strict mode will see that removal applied rather than keeping the older copy. That is a small design decision with real consequences for anyone whose archive is shared.

The CLI surface is wide and JSON-stable

For launchers, agents and CI the tool exposes stable JSON through four commands.

discrawl status --json
discrawl diagnostics --json
discrawl coverage --json
discrawl failures --json

The README suggests starting with status and doctor and then using the command reference for the full control surface. The word stable matters for the automation audience, since a script that parses these outputs will break if the shape changes, and a project that publishes a reference document for the commands is making a promise about that. The metrics side is separate: for public server-size observations without a bot token you use metrics collect with its own metrics database, recording approximate members and online presence, where online presence does not measure active posters. metrics import preserves historical observations and metrics status reports their freshness. The distinction between approximate counts and active posters is stated rather than glossed over.

Storage, credentials and the container

Discrawl follows platform storage conventions, using XDG directories on Linux and the Library folder on macOS, and configuration can read the bot token from an environment variable or from the operating system keyring, with the token never written into snapshots. The container image shows the same structure in environment variables, with XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_CACHE_HOME and XDG_STATE_HOME all pointing under a data volume, and a dedicated unprivileged user created with a fixed identifier and a home directory. The build stage compiles with CGO disabled and the version string injected at link time, and the runtime image is Alpine with a data volume and the binary as the entrypoint. The repository also carries a gitleaks configuration, which is the standard way to keep credentials out of a history, and the Makefile has a snapshot target described as building credential-free release artifacts.

Editorial conclusion

Use discrawl when you need durable, searchable history of a Discord server you administer or belong to, because the archive lands in SQLite and the FTS5 search needs no external service, so you can search years of messages offline and query them with SQL. Do not treat it as a way to read someone else's messages, because the wiretap mode only reads what Discord Desktop already cached locally and the bot mode needs your own bot token. Verify first which archive source you are configuring, because the four have different setup and different privacy consequences, that the token stays in the environment or the keyring and never in a published snapshot, and that your local copy of the Desktop cache is the one you intend to import, since the import is one-way.

Frequently asked questions

Official sources

1. License: MIT
2. openclaw/discrawl on GitHub
3. Project website
4. README
5. Releases