From c6c65b525e8dfa4941a0c6881b8145ce1a66044f Mon Sep 17 00:00:00 2001
From: Rustam Gilyazov <16064414+rusq@users.noreply.github.com>
Date: Sun, 19 Jan 2025 09:10:28 +1000
Subject: [PATCH] Update documentation to describe machine ID override

---
 cmd/slackdump/internal/man/assets/transfer.md | 62 +++++++++++++++++++
 cmd/slackdump/internal/man/transfer.go        | 16 +++++
 cmd/slackdump/main.go                         |  1 +
 slackdump.1                                   |  6 ++
 4 files changed, 85 insertions(+)
 create mode 100644 cmd/slackdump/internal/man/assets/transfer.md
 create mode 100644 cmd/slackdump/internal/man/transfer.go

diff --git a/cmd/slackdump/internal/man/assets/transfer.md b/cmd/slackdump/internal/man/assets/transfer.md
new file mode 100644
index 00000000..65a8966f
--- /dev/null
+++ b/cmd/slackdump/internal/man/assets/transfer.md
@@ -0,0 +1,62 @@
+# Transferring Credentials to Another Computer
+
+__Difficulty__: Advanced.
+
+At times you may need to transfer the credentials to another computer or
+system, such as CI/CD.  As the credentials are encrypted with the machine-specific
+key (machine ID), the credentials will not work straight away.
+
+Slackdump supports Machine ID override, which allows you to define the machine ID
+for a chosen workspace.  Using the same Machine ID on your local and remote systems
+will allow you to use the same credentials on both.
+
+__IMPORTANT__:  Never share your custom machine ID with anyone.  The machine ID
+is a secret key to your login information.
+
+To transfer the credentials to another system, follow these steps:
+
+1. Reauthenticate in the workspace you want to transfer by specifying the
+   machine ID override with `-machine-id` flag. For example: 
+    
+   ```bash
+   slackdump workspace new -machine-id="my-machine-id" your_workspace
+   ```
+
+   This will create a new workspace file with the machine ID override.
+
+2. Run the `slackdump workspace list` command to get the workspace file name,
+   for example: `your_workspace.bin`
+
+3. Find out the slackdump cache directory location on your system by running:
+
+   ```bash
+   slackdump tools info
+   ```
+
+   Slackdump cache location will be in "workspace" section, "path" field.  If
+   you have `jq` installed, you can run:
+
+   ```bash
+   slackdump tools info | jq -r '.workspace.path'
+   ```
+
+5. Install slackdump on the remote system.
+
+6. Repeat the step 3 on the remote system to find out the cache directory.
+
+7. Create it if it doesn't exist
+
+8. Copy the workspace file and `workspace.txt` file from the cache directory to
+   the remote system.
+
+9. Verify that the workspace is available and credentials are working by running:
+
+   ```bash
+   slackdump workspace list -a -machine-id="my-machine-id" 
+   ```
+
+   on the remote system.
+   You should see OK in the last "error" column.  If you see "failed to load
+   stored credentials", it means that the credentials are not working.
+
+10. You can now use the credentials on the remote system.
diff --git a/cmd/slackdump/internal/man/transfer.go b/cmd/slackdump/internal/man/transfer.go
new file mode 100644
index 00000000..506ae198
--- /dev/null
+++ b/cmd/slackdump/internal/man/transfer.go
@@ -0,0 +1,16 @@
+package man
+
+import (
+	_ "embed"
+
+	"github.com/rusq/slackdump/v3/cmd/slackdump/internal/golang/base"
+)
+
+//go:embed assets/transfer.md
+var transferMd string
+
+var Transfer = &base.Command{
+	UsageLine: "transfer",
+	Short:     "transfering credentials to another system",
+	Long:      transferMd,
+}
diff --git a/cmd/slackdump/main.go b/cmd/slackdump/main.go
index 0fef20b2..06dc5a5f 100644
--- a/cmd/slackdump/main.go
+++ b/cmd/slackdump/main.go
@@ -60,6 +60,7 @@ func init() {
 		man.Login,
 		man.Chunk,
 		man.Migration,
+		man.Transfer,
 	}
 }
 
diff --git a/slackdump.1 b/slackdump.1
index 5d27f832..1c2fbb9f 100644
--- a/slackdump.1
+++ b/slackdump.1
@@ -155,6 +155,12 @@ 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