diff --git a/Documentation/SwiftlyDocs.docc/SwiftlyDocs.md b/Documentation/SwiftlyDocs.docc/SwiftlyDocs.md
index bd0b4da0..ed4a89d6 100644
--- a/Documentation/SwiftlyDocs.docc/SwiftlyDocs.md
+++ b/Documentation/SwiftlyDocs.docc/SwiftlyDocs.md
@@ -14,6 +14,7 @@ Install and manage your Swift programming language toolchains.
 
 - <doc:install-toolchains>
 - <doc:use-toolchains>
+- <doc:shell-autocompletion>
 - <doc:uninstall-toolchains>
 - <doc:update-toolchain>
 - <doc:automated-install>
diff --git a/Documentation/SwiftlyDocs.docc/shell-autocompletion.md b/Documentation/SwiftlyDocs.docc/shell-autocompletion.md
new file mode 100644
index 00000000..55c16220
--- /dev/null
+++ b/Documentation/SwiftlyDocs.docc/shell-autocompletion.md
@@ -0,0 +1,64 @@
+# Add Shell Auto-completions
+
+Swiftly can generate shell auto-completion scripts for your shell to automatically complete subcommands, arguments, options and flags. It does this using the [swift-argument-parser](https://apple.github.io/swift-argument-parser/documentation/argumentparser/installingcompletionscripts/), which has support for Bash, Z shell, and Fish.
+
+You can ask swiftly to generate the script using the hidden `--generate-completion-script` flag with the type of shell like this:
+
+```
+swiftly --generate-completion-script <shell>
+```
+
+@TabNavigator {
+    @Tab("zsh") {
+        If you have [oh-my-zsh](https://ohmyz.sh/) installed then this command will install the swiftly completions into the default directory:
+
+        ```
+        swiftly --generate-completion-script zsh > ~/.oh-my-zsh/completions/_swiftly
+        ```
+
+        Otherwise, you'll need to add a path for completion scripts to your function path, and turn on completion script autoloading. First, add these lines to ~/.zshrc:
+
+        ```
+        fpath=(~/.zsh/completion $fpath)
+        autoload -U compinit
+        compinit
+        ```
+
+        Next, create the completion directory and add the swiftly completions to it:
+
+        ```
+        mkdir -p ~/.zsh/completion && swiftly --generate-completion-script zsh > ~/.zsh/completions/swiftly
+        ```
+    }
+
+    @Tab("bash") {
+        If you have [bash-completion](https://github.com/scop/bash-completion) installed then this command will install the swiftly completions into the default directory:
+
+        ```
+        swiftly --generate-completion-script bash > swiftly.bash
+        # copy swiftly.bash to /usr/local/etc/bash_completion.d
+        ```
+
+        Without bash-completion create a directory for the completion and generate the script in there:
+
+        ```
+        mkdir -p ~/.bash_completions && swiftly --generate-completion-script bash > ~/.bash_completions/swiftly.bash
+        ```
+
+        Add a line to source that script in your `~/.bash_profile` or `~/.bashrc` file:
+
+        ```
+        source ~/.bash_completions/swiftly.bash
+        ```
+    }
+
+    @Tab("fish") {
+        Generate the completion script to any path in the environment variable `$fish_completion_path`. Typically this command will generate the script in the right place:
+
+        ```
+        swiftly --generate-completion-script fish > ~/.config/fish/completions/swiftly.fish
+        ```
+    }
+}
+
+Once you have installed the completions you can type out a swiftly command, and press a special key (e.g. tab) and the shell will show you the available subcommand, argument, or options to make it easier to assemble a working command-line.