Skip to content

Commit 14b2fea

Browse files
rusqrusq
authored
Merge pull request #625 from rusq/doc-spike
Documentation refresh
2 parents 3bb630c + b25f622 commit 14b2fea

18 files changed

+1602
-684
lines changed

‎README.md‎

Lines changed: 33 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ files and emojis. Generate Slack Export without admin privileges.
1111
- [Join the discussion in Telegram](https://t.me/slackdump).
1212
- [Buy me a cup of tea](https://ko-fi.com/rusq_), or use **GitHub Sponsors**
1313
button on the top of the page.
14-
- [![Go reference](https://pkg.go.dev/badge/github.com/rusq/slackdump/v3.svg)][godoc]
14+
- [![Go reference](https://pkg.go.dev/badge/github.com/rusq/slackdump/v4.svg)][godoc]
1515
- [Using with AI Agents (MCP Server)](#slackdump-mcp-server)
1616
- [Slack MCP Server (no permissions required)](https://github.com/korotovsky/slack-mcp-server)
1717
- [Github CLI Slackdump extension](https://github.com/wham/gh-slackdump)
@@ -21,8 +21,9 @@ files and emojis. Generate Slack Export without admin privileges.
2121
- [SlackLogViewerとSlackdumpを一緒に使用する](https://kenkyu-note.hatenablog.com/entry/2022/09/02/090949)
2222
- [v1 Overview on Medium.com](https://medium.com/@gilyazov/downloading-your-private-slack-conversations-52e50428b3c2) (outdated)
2323

24-
[godoc]: https://pkg.go.dev/github.com/rusq/slackdump/v3/
25-
[mmost]: doc/usage-export.rst
24+
[godoc]: https://pkg.go.dev/github.com/rusq/slackdump/v4/
25+
[mmost]: doc/usage-export.md
26+
[ug]: doc/README.md
2627

2728

2829
> [!WARNING]
@@ -56,14 +57,15 @@ There are several modes of operation
5657
1. Dumping messages and threads
5758
1. Creating a Slack Export in Mattermost or Standard modes.
5859
1. Creating an Archive (Sqlite database or stored as json+gz)
60+
1. Converting an archive to other formats (Export, Dump).
5961
1. Emoji download mode.
6062
1. Viewing Slack export, dump or archive files or directories (displays images).
6163
1. Search mode (messages and files).
6264
1. Resuming previous archive (adding new messages to an existing archive).
6365
1. Local MCP Server to use with Opencode, Claude, or any other AI tool
6466
supporting mcp over STDIO or HTTP.
6567

66-
Run `slackdump help` to see all available options:
68+
Run `slackdump help` to see all available options.
6769

6870
## Installation and Quickstart
6971

@@ -104,11 +106,9 @@ On other Operating Systems, please follow these steps:
104106
- Quickstart guide: `slackdump help quickstart`, read [online][man-quickstart].
105107
- Generic command overview: `man ./slackdump.1`
106108
- [Ez-Login 3000](https://github.com/rusq/slackdump/wiki/EZ-Login-3000) Guide.
107-
- V2 to V3 migration notes: `slackdump help v2migrate`, read [online][man-v2migrate].
108-
- What's new in V3: `slackdump help whatsnew`, read [online][man-changelog].
109+
- What's new in V4: `slackdump help whatsnew`, read [online][man-changelog].
109110

110111
[man-quickstart]: https://github.com/rusq/slackdump/blob/master/cmd/slackdump/internal/man/assets/quickstart.md
111-
[man-v2migrate]: https://github.com/rusq/slackdump/blob/master/cmd/slackdump/internal/man/assets/v2migr.md
112112
[man-changelog]: https://github.com/rusq/slackdump/blob/master/cmd/slackdump/internal/man/assets/changelog.md
113113

114114
## Running Slackdump from a Repo Checkout
@@ -171,15 +171,31 @@ export results:
171171

172172
# Slackdump MCP server
173173

174-
Slackdump offers a read-only MCP server that has the following features:
174+
Slackdump offers a read-only MCP server with the following features:
175175
- analyse the data in the archive (any type)
176176
- provide help with command line flags
177177

178-
To learn how to use it and set up, see
178+
Available MCP tools:
179+
180+
| Tool | Description |
181+
|------|-------------|
182+
| `load_source` | Open (or switch to) a Slackdump archive at runtime |
183+
| `list_channels` | List all channels in the archive |
184+
| `get_channel` | Get detailed info for a channel by ID |
185+
| `list_users` | List all users/members |
186+
| `get_messages` | Read messages from a channel (paginated) |
187+
| `get_thread` | Read all replies in a thread |
188+
| `get_workspace_info` | Workspace/team metadata |
189+
| `command_help` | Get CLI flag help for any slackdump subcommand |
190+
191+
The server supports both **stdio** (agent-managed) and **HTTP** transports.
192+
193+
To learn how to set it up with Claude Desktop, VS Code/GitHub Copilot, or
194+
OpenCode, see:
179195
```
180196
slackdump help mcp
181197
```
182-
or refer to [Slackdump MCP command help page][mcp-doc]
198+
or refer to the [Slackdump MCP command help page][mcp-doc].
183199

184200
[mcp-doc]: https://github.com/rusq/slackdump/blob/master/cmd/slackdump/internal/mcp/assets/mcp.md
185201

@@ -188,7 +204,7 @@ or refer to [Slackdump MCP command help page][mcp-doc]
188204
Download:
189205

190206
```shell
191-
go get github.com/rusq/slackdump/v3
207+
go get github.com/rusq/slackdump/v4
192208
```
193209

194210

@@ -201,8 +217,8 @@ import (
201217
"context"
202218
"log"
203219

204-
"github.com/rusq/slackdump/v2"
205-
"github.com/rusq/slackdump/v2/auth"
220+
"github.com/rusq/slackdump/v4"
221+
"github.com/rusq/slackdump/v4/auth"
206222
)
207223

208224
func main() {
@@ -298,6 +314,10 @@ supporting the project:
298314
- Robert Z.
299315
- Sudhanshu J.
300316

317+
## License
318+
319+
Slackdump is licensed under the [GNU Affero General Public License v3.0 (AGPLv3)](LICENSE).
320+
301321
# Bulletin Board
302322

303323
Messages that were conveyed with the donations:

‎doc/README.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Slackdump User Guide
2+
3+
## Table of Contents
4+
5+
- [Installation](#installation)
6+
- [Logging In](#logging-in)
7+
- [Automatic (browser-based) login](login-automatic.md)
8+
- [Manual login (token/cookie)](login-manual.md)
9+
- [Usage](#usage)
10+
- [Archiving a workspace](usage-archive.md)
11+
- [Listing users/channels](usage-list.md)
12+
- [Dumping messages and threads](usage-channels.md)
13+
- [Creating a Slack Export](usage-export.md)
14+
- [Downloading all Emojis](usage-emoji.md)
15+
- [Compiling from Sources](compiling.md)
16+
- [Troubleshooting](troubleshooting.md)
17+
18+
## Installation
19+
20+
Installing is simple — download the latest Slackdump from the
21+
[Releases](https://github.com/rusq/slackdump/releases) page, extract and run it:
22+
23+
1. Download the archive from the [Releases](https://github.com/rusq/slackdump/releases)
24+
page for your operating system.
25+
26+
> **macOS users** can use `brew install slackdump` to install the latest version.
27+
28+
2. Unpack the archive.
29+
3. Change directory to where you unpacked it.
30+
4. Run `./slackdump` (or `slackdump.exe` on Windows) to start the wizard.
31+
32+
For compiling from sources, see [Compiling from Sources](compiling.md).
33+
34+
## Logging In
35+
36+
See [Automatic Login](login-automatic.md) for the recommended browser-based
37+
login methods (Interactive, User Browser, Headless, and QR Code / Sign in on
38+
Mobile).
39+
40+
For manual token/cookie authentication (headless/CI environments), see
41+
[Manual Authentication](login-manual.md).
42+
43+
To import a saved token/cookie file:
44+
45+
```shell
46+
slackdump workspace import <filename>
47+
```
48+
49+
## Usage
50+
51+
There are several modes of operation:
52+
53+
| Command | Description |
54+
|---------|-------------|
55+
| `slackdump archive` | Archive the whole workspace (or specific channels) to a SQLite database |
56+
| `slackdump export` | Export to Slack-compatible ZIP (Standard or Mattermost format) |
57+
| `slackdump dump` | Dump individual conversations or threads to JSON |
58+
| `slackdump list users` | List all workspace users |
59+
| `slackdump list channels` | List all visible channels |
60+
| `slackdump emoji` | Download all workspace custom emojis |
61+
| `slackdump resume` | Resume a previously interrupted archive |
62+
| `slackdump convert` | Convert an archive to another format |
63+
| `slackdump view` | View a dump, export or archive in the browser |
64+
| `slackdump search` | Dump Slack search results |
65+
| `slackdump mcp` | Start a local MCP server for AI agent access |
66+
67+
Run `slackdump help` to see all available commands, or `slackdump help <command>`
68+
for detailed help on a specific command.
69+
70+
## Beginner's Guide to the Command Line
71+
72+
If you have no experience with the Linux/macOS Terminal or Windows Command
73+
Prompt, the [Unix Shell Guide](https://swcarpentry.github.io/shell-novice/)
74+
is a good starting point.

‎doc/README.rst‎

Lines changed: 0 additions & 61 deletions
This file was deleted.

‎doc/compiling.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Compiling from Sources
2+
3+
[Back to User Guide](README.md)
4+
5+
## Install with `go install`
6+
7+
If you have Go installed, you can build and install the latest release directly:
8+
9+
```shell
10+
go install github.com/rusq/slackdump/v4/cmd/slackdump@latest
11+
```
12+
13+
## Build from a Repository Checkout
14+
15+
Clone the repository and build:
16+
17+
```shell
18+
git clone https://github.com/rusq/slackdump.git
19+
cd slackdump
20+
go build -o slackdump ./cmd/slackdump
21+
```
22+
23+
Or run without building a binary:
24+
25+
```shell
26+
go run ./cmd/slackdump
27+
```
28+
29+
See `go.mod` for the minimum required Go version.
30+
31+
## Build with Version Info (Release Build)
32+
33+
```shell
34+
make
35+
```
36+
37+
This produces a binary with the correct version string embedded. Requires
38+
`make` and the Go toolchain.
39+
40+
[Back to User Guide](README.md)

‎doc/compiling.rst‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎doc/login-automatic.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Automatic (Browser-Based) Login
2+
3+
[Back to User Guide](README.md)
4+
5+
Slackdump's automatic login is handled by the
6+
[`slackauth`](https://github.com/rusq/slackauth) library, which drives a
7+
browser via the [Rod](https://go-rod.github.io/) / CDP protocol to capture the
8+
Slack session token and cookie on your behalf.
9+
10+
Run the following command to add a new workspace:
11+
12+
```bash
13+
slackdump workspace new
14+
```
15+
16+
You will be asked for the workspace name (the part before `.slack.com`), then
17+
prompted to choose one of four login methods described below.
18+
19+
## Login Methods
20+
21+
### Interactive (recommended for most users)
22+
23+
A clean browser window opens on the Slack login page. Log in as usual —
24+
including any SSO, MFA, or company identity provider steps. The browser
25+
closes automatically once the session token and cookie have been captured.
26+
27+
Choose **Interactive** unless your workspace uses Google Authentication (use
28+
**User Browser** instead) or you know your email/password login works
29+
headlessly.
30+
31+
### User Browser
32+
33+
Instead of launching a bundled browser, Slackdump opens **your own installed
34+
browser** (Chrome, Firefox, etc.) on the Slack login page. Your existing
35+
browser profile is used, which means Google Authentication and other flows that
36+
block embedded browsers will work.
37+
38+
When prompted, select the browser you want to use from the list of detected
39+
browsers.
40+
41+
### Automatic (Headless)
42+
43+
Slackdump automates the email + password login flow entirely without opening a
44+
visible browser window. You will be prompted to enter your email and password
45+
in the terminal. If Slack sends a confirmation code to your email, you will
46+
also be asked to enter that.
47+
48+
**Limitations:** only works with plain email/password workspaces. Does not
49+
support SSO, Google, or passwordless (OTP-only) workspaces.
50+
51+
### QR Code (Sign in on Mobile)
52+
53+
Use this method when other browser-based methods are blocked (e.g. Google Auth
54+
blocks the embedded browser, or your workspace enforces strict SSO policies).
55+
It uses the Slack "Sign in on mobile" QR code flow, which still relies on Rod
56+
internally to exchange the QR image for a session token.
57+
58+
**Steps:**
59+
60+
1. In the logged-in Slack desktop app or web client, click your **workspace
61+
name** in the upper-left corner.
62+
2. Choose **Sign in on mobile**.
63+
3. Slack displays a QR code. **Right-click the QR code image** and choose
64+
**Copy Image**.
65+
4. Switch to the Slackdump terminal — it will be showing a text field titled
66+
"Paste QR code image data into this field".
67+
5. Paste the copied image data into that field and press **Enter**.
68+
69+
Slackdump exchanges the base64-encoded image with Slack's API and captures the
70+
resulting session token and cookie automatically.
71+
72+
## Troubleshooting
73+
74+
| Symptom | Fix |
75+
|---------|-----|
76+
| Browser fails to launch or closes immediately | Close any existing Chrome/browser processes, then retry. See [Troubleshooting](troubleshooting.md#browser-fails-to-launch-or-closes-immediately). |
77+
| Slack shows "browser not supported" | Switch to **User Browser** or use [manual login](login-manual.md). |
78+
| Google / SSO login blocked | Use **User Browser** or **QR Code** method. |
79+
| Login hangs after completing 2FA / SSO | Use **QR Code** method or fall back to [manual login](login-manual.md). |
80+
| Running in Docker / CI | Browser-based login requires an interactive display. Use [manual login](login-manual.md) instead. |
81+
82+
[Back to User Guide](README.md)

0 commit comments

Comments
 (0)