docs: add shell completion to nav.js (#1357)

* docs: add shell completion to nav.js * docs: update nav.js We want Bearer Cloud Guide to be the last item * docs(guides): improve completions guide * Apply suggestions from code review Co-authored-by: elsapet <[email protected]> * docs: completion guide feedback --------- Co-authored-by: gotbadger <[email protected]> Co-authored-by: Philip Hayton <[email protected]> Co-authored-by: elsapet <[email protected]>
Bearer · Oct 31, 2023 · f1ce4c2 · f1ce4c2
1 parent 424155a
commit f1ce4c2
Show file tree

Hide file tree

Showing 2 changed files with 19 additions and 27 deletions.
diff --git a/docs/_data/nav.js b/docs/_data/nav.js
@@ -40,6 +40,10 @@ module.exports = [
         name: "Run a data flow report",
         url: "/guides/dataflow/",
       },
+      {
+        name: "Shell completions",
+        url: "/guides/shell-completion/",
+      },
       {
         name: "Using Bearer Cloud",
         url: "/guides/bearer-cloud/",

diff --git a/docs/guides/shell-completion.md b/docs/guides/shell-completion.md
@@ -2,39 +2,38 @@
 title: Enable Completion Script
 ---
 
-# Enable shell completion
+# Enabling shell completions
 
-Below is example steps to enable shell completion feature for `bearer` cli:
+Completions make it easier to use Bearer on the command line. In this guide we will cover how to set everything up.
 
-## 1. Know your current shell
+## Discover your current shell
 
 ```bash
 $ echo $SHELL
-/bin/zsh # For this example it is zsh, but will be vary depend on your $SHELL, maybe /bin/bash or /bin/fish
+/bin/zsh
 ```
+In our example it's zsh, but this will vary depending on your $SHELL.
 
-## 2. Run `completion` command to get sub-commands
+## Test the completion scripts
 
-``` bash
-bearer completion -h
+We currently support `zsh` `bash` and `fish`. To load completions in your current shell session you can run the following:
+
+```bash
+source <(bearer completion zsh); compdef _bearer bearer
 ```
 
-Generate the autocompletion script for the zsh shell.
+Now you can test completions. Type `bearer` into your terminal and hit the tab button on your keyboard.
 
-If shell completion is not already enabled in your environment you will need
-to enable it.  You can execute the following once:
+**Note:** if completions are not already enabled in your environment you will need
+to enable it. In zsh you can execute the following once:
 
 ```bash
 echo "autoload -U compinit; compinit" >> ~/.zshrc
 ```
 
-To load completions in your current shell session:
-
-```bash
-source <(bearer completion zsh); compdef _bearer bearer
-```
+## Final setup
 
-To load completions for every new session, execute once:
+To load completions for every new session you can add the test command to your `~/.zshrc` or similar. Alternatively if you are using zsh you can execute the following once:
 
 ### Linux
 
@@ -50,14 +49,3 @@ bearer completion zsh > $(brew --prefix)/share/zsh/site-functions/_bearer
 
 You will need to start a new shell for this setup to take effect.
 
-## 3. Run the sub-commands following the instruction
-
-```bash
-bearer completion zsh > "${fpath[1]}/_bearer"
-```
-
-## 4. Start a new shell and you can see the shell completion
-
-```bash
-bearer [tab]
-```