slackdump.1

.\" https://man.openbsd.org/mdoc.7
.\" macros:
.de BOOL
If set to
.Dq Ar true
(or any of 
.Dq Ar 1
,
.Dq Ar t
or
.Dq Ar yes
),
..

.Dd $Mdocdate$
.Dt SLACKDUMP 1
.Os
.Sh NAME
.Nm slackdump
.Nd archive Slack workspace contents locally.
.Sh SYNOPSIS
.Nm slackdump
.Ar command Op Cm subcommand
.Op Fl flags
.Op Ar args ...
.Sh DESCRIPTION
The
.Nm
utility dumps Slack workspace contents.  Currently it supports the
following Slack entities:
.Bl -tag -compact -width messages -offset ident
.It Em messages
Includes all messages in all channels, direct, and group messages.
.It Em replies
Includes all message replies or, in other words — threads.
.It Em files
Files are dumped along with messages they belong to.
.It Em emojis
Emojis are dumped along with their index which contains their names and aliases
as a JSON file, in the "slow" mode -- includes the user ID of the uploader.
.It Em users
Users includes full profile information without custom fields.
.It Em channels
Channels, that are visible to the current authenticated user.  This includes:
.Bl -dash -compact
.It
current and archive public channels including those that this user is not a
member of;
.It
private group conversations;
.It
direct messages (private conversations between two users).
.El
.It Em search
Searches and saves messages and/or files from the workspace.
.El
.Pp
If no command is given, on a dumb terminal, the 
.Cm help
command is assumed.  On an interactive terminal a list of options will
be presented, allowing the user to enter an interactive mode (wizard),
display help, or exit.
.Sh COMMANDS
The following commands are supported (listed in alphabetical order):
.Bl -tag -width workspace
.It Cm archive
Archive the workspace data in the Chunk format, that can be converted to
other formats, such as Slack Export or Dump.
.It Cm config Ar subcommand
Allows to perform different operations on the API limits configuration
files.
.It Cm convert
Convert between formats.
.It Cm dump
Dump selected channels or threads.
.It Cm emoji
Export Slack workspace emojis.
.It Cm export
Export workspace contents.
.It Cm format
Format the conversations, users, and channels as human readable files.
It supports TEXT and CSV formats.
.It Cm help Ar command
Display help.  To get the subcommand help, use the combination of
.Cm main_command Cm help Ar subcommand
For example, to get help on the
.Ar new
subcommand of the
.Cm workspace
command, run the following:
.Bd -literal -offset indent
.Nm Cm workspace Cm help Ar new
.Ed
.It Cm list
List channels or users in the desired format
.Pq default output is text
.It Cm search Ar subcommand
Search for messages, files, or both in the workspace and save the results in
archive format.  The discovered files are saved to disk as well.
.It Cm tools Ar subcommand
Contains various diagnostic and convenience utilities.  Developers might ask
to run these commands to help with debugging.  See TOOLS section for more
information.
.It Cm version
Display version information.
.It Cm view
Allows to view the exported data (archive, dump and export) in the browser.
.It Cm wiz
Starts up an interactive mode.
.It Cm workspace
Manage stored credentials for authenticated workspaces, or authenticates in a
new workspace.
.El
.\"
.Sh FLAGS
This section lists all available flags, availability of which depends on the
command.  The flags are listed in alphabetical order.
.Bl -tag -width -base dir
.It Fl api-config Ar path
Use the specified API limits configuration TOML file (see the
.Cm config
command).
.It Fl autologin-timeout Ar duration
Headless autologin timeout, without the browser starting time, just the
interaction time. The duration must be specified in the following format:
.Dq XhYmZs ,
for example,
.Dq 1h20m32s
would set the timeout to 1 hour, 20 minutes, 32 seconds.
.It Fl o Ar path
Specifies the output directory or zip file where all data will be stored.
If the path ends with
.Dq .zip ,
the data will be stored in the zip file, otherwise
it will be stored in the directory.
.Pp
If the flag is not specified, Slackdump defaults to creating a zip file in the
current directory using the following pattern:
.Dq slackdump_YYYYMMDD_HHMISS.zip ,
where
.Dq YYYYMMDD_HHMISS
is the current date and time.  For example:
.Bd -literal -offset indent
slackdump_20201231_235959.zip
.Ed
.It Fl browser Ar firefox | chromium
Specifies the browser to use for the authentication.  The default is Firefox.
.It Fl cache-dir Ar path
Specifies the directory where the authentication information and user/channel
cache is stored.  If the flag is not specified, the cache is stored in the
system cache directory.
.It Fl cookie Ar cookie | cookie_file
.It Fl files=true|false
Enables or disables attachment files downloading.  The default is enabled.  To
disable downloading, use
.Dq Fl files=false .
.It Fl log Ar path
Specifies the log file path and or filename.  If the flag is not specified, the
log is written to the error output (STDERR).
.It Fl log-json=true|false
Enables or disables JSON log format.  The default is disabled.
.It Fl token Ar token
Specifies the token to use for the authentication.  This flag is only used
with the manual authentication methods.
.It Fl machine-id Ar value
Allows to override the machine ID. To read how to use it to transfer the credentials
between machine, run:
.Bd -literal -offset indent
slackdump help transfer
.Ed
.It Fl member-only
Specify this flag to export only conversations (channels) that the current user
is part of.  Works only if the list of channels/threads is not explicitly
specified.
.It Fl no-user-cache
Disables caching of users for the subcommands of the
.Cm list
command.
.It Fl no-chunk-cache
Disables caching of chunks for the
.Cm convert
command.  This may be useful on small archives.  For big archives caching is
beneficial, as it allows to reduce the processing time.
.It Fl time-from Ar YYYY-MM-DDTHH:MI:SS
Allows to specify the start time.  The time is specified in the format
.Dq YYYY-MM-DDTHH:MI:SS
where
.Sq T
is a literal character separating the date and time, for example
.Dq 2020-12-311T23:59:59
.It Fl time-to Ar YYYY-MM-DDTHH:MI:SS
Allows to specify the end time.  See the
.Fl time-from
flag for the format.
.It Fl trace Ar filename
Enables tracing and writes the trace to the specified file.
.It Fl user-cache-retention Ar duration
Specifies the duration for which the user cache is kept.  The default is
.Dq 1h
.Ns .
The duration is specified in the format accepted by the Go time package.
For example, to specify the duration of 1 hour 30 minutes and 55 seconds, use
.Dq 1h30m55s
.Ns .
.It Fl v
Enables verbose output, prints a lot of debugging information.
.It Fl workspace Ar name
Allows to override the currently selected workspace for the session.
See also the
.Cm workspace Ar select
command.
.El
.\"
.Sh USAGE
.Ss Quickstart
The quickest way to get started is to run the following command:
.Bl -enum -compact
.It
Authenticate in a new workspace using the
.Cm workspace
.Ar new
command;
.It
Run
.Cm archive
,
.Cm export
or
.Cm dump
, depending on your requirements.  The
.Dq archive
format can be converted to
.Dq export
or
.Dq dump
formats using the
.Cm convert
command.
.El
See also:
.Bd -literal -offset indent
.Nm Cm help Ar quickstart
.Ed
.Sh AUTHENTICATION
Slackdump supports multiple authentication methods listed below.
.Ss Automatic login (EZ-LOGIN 3000)
This is the default authentication mode, and so far is the most convenient one.
It requires no additional configuration and works out of the box.  However, it
is not supported on all systems:  it requires GUI and x64 architecture, and may
require some additional steps on CentOS and other Redhat derived systems.

If the automatic login does not work for some reason, you can try to use one of
the manual login methods, described in the next section.

This method works on Single-Sign-On enabled workspaces as well in most cases.

For Google Authentication, you must use the "User Browser" login method to
avoid bot detection algorithms.

.Ss Manual login methods
.Bl -tag -width token+cookie
.It Em token
This method requires Application
.Pq xapp-
, Bot
.Pq xoxb-
or a Legacy
.Pq xoxp-
token. You can get these tokens (except Legacy) from the Slack
Workspace Administration page.  See the
.Lk https://api.slack.com/authentication/token-types "Slack documentation"
for more details.
.Pp
.Sy Note:
You will not be able to access your DMs with the Application or Bot tokens, and
Legacy tokens are deprecated.
.It Em token+cookie
This is the pair of the Client Token
.Pq xoxc-
and a 
.Dq d=
Browser Cookie
.Pq xoxd=
value that you can get from your browser manually following the instructions in
the documentation.
.It Em token+cookie file
This is the same as above, but it requires the 
.Dq cookie.txt
file, exported from you Browser session in Mozilla format.  On Firefox, you could use
.Lk https://addons.mozilla.org/en-US/firefox/addon/cookies-txt/ "Cookies.txt"
extension.
.Sy Note:
Some browser extensions may be unsafe and may expose your private data, so use them at
your own risk.  The authors of this utility do not endorse any of the
extensions mentioned above.
.El
.Pp
Read more on how to get the token and cookie from your logged-in browser 
session by running
.Bd -literal -offset indent
.Nm Cm help Ar login
.Be
.\" 
.Sh TOOLS
The following tools are available:
.Bl -tag -width uninstall
.It Em encrypt
encrypt files for secure transmission, i.e. encrypting trace.out before
posting it in Github Issues.
.It Em eztest
test the EZ-LOGIN 3000 method.
.It Em hydrate
allows to "hydrate" the native Slack Exports with attachments.  It downloads
attachments from Slack and creates a copy of the export with downloaded files.
.It Em info
show information about Slackdump environment
.It Em obfuscate
obfuscate the sensitive data in Slackdump archive.  Works only on
archive file format.
.It Em redownload
downloads any files that failed to download while running the archival process.
.It Em uninstall
uninstall Slackdump components or purge it from the system.
.It Em thread
thread utility, used to create threads in the Slack workspace for tests.
.El
.Sh ENVIRONMENT
.Bl -tag -width SLACK_WORKSPACE
.It Ev BASE_LOC
Contains path to a directory or zip file where all data will be stored.  See
.Fl base
flag for more details.
.It Ev CACHE_DIR
Contains path to a directory where cache files will be stored.  See flag
.Fl cache-dir
for more details.
.It Ev DEBUG
.BOOL
enables debug output and switches the viewer output to RAW (JSON) format.
.It Ev JSON_LOG
.BOOL
enables JSON log format.
.It Ev LOG_FILE
Contains path to a file where log output will be written.
.It Ev MACHINE_ID_OVERRIDE
Allows to override the Machine ID when opening or saving credentials and cache
files.  See flag
.Fl machine-id
for more details.
.It Ev SLACK_COOKIE
Contains Slack cookie (for token+cookie-based authentication).  See
.Sx Authentication
for more details.
.It Ev SLACK_TOKEN
Contains Slack token (for token-based authentication).  See
.Sx Authentication
for more details.
.It Ev SLACK_WORKSPACE
Allows to specify Slack workspace name (overrides currently selected
workspace).  See 
.Ar workspace
command for more details.
.It Ev TRACE_FILE
Contains path to a file where trace output will be written.
.El
.\" For sections 1, 6, 7, and 8 only.
.Sh FILES
.Bl -tag -width secrets.txt -compact
.It Sy .env
Contains environment variables that will be loaded during the startup.  These
variables override the environment variables set in the environment.
.It Sy .env.txt
See
.Em .env
.It Sy secrets.txt
See
.Em .env
.\" .Sh EXIT STATUS
.\" For sections 1, 6, and 8 only.
.Sh EXAMPLES
Getting help on a specific command:
.Bd -literal -offset indent
.Nm Cm help Ar <command>
.Ed
.Pp
Authenticate in a new workspace
.Lk https://myworkspace.slack.com
:
.Bd -literal -offset indent
.Nm Cm workspace Cm new Ar myworkspace
.Ed
.Pp
Run full workspace export:
.Bd -literal -offset indent
.Nm Cm export
.Ed
.Pp
Run full workspace export with debug output:
.Bd -offset indent
DEBUG=1 
.Nm Cm export
.Ed
.\" .Sh DIAGNOSTICS
.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
.\" .Sh ERRORS
.\" For sections 2, 3, 4, and 9 errno settings only.
.\" .Sh SEE ALSO
.\" .Xr foobar 1
.\" .Sh STANDARDS
.Sh HISTORY
Slackdump was created as a tool to dump private messages from Slack in 2018, and
was released as an GPL-3 Open Source application to public in October 2021.
.Sh AUTHORS
The
.Nm
was written by
.An Lk https://github.com/rusq "@rusq"
with the help of a number of contributors listed on 
.Lk https://github.com/rusq/slackdump "Slackdump Homepage"
.\" .Sh CAVEATS
.\" .Sh BUGS
.\" .Sh SECURITY CONSIDERATIONS
.\" Not used in OpenBSD.