From c63adc57ec48dd2af44b57319bbc8748c9daaad2 Mon Sep 17 00:00:00 2001 From: Preston Date: Thu, 19 Feb 2026 15:25:23 -0600 Subject: [PATCH 1/4] Added documentation on cli autocomplete integration. --- docs/09-tools/04-shell-completion.md | 49 ++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/09-tools/04-shell-completion.md diff --git a/docs/09-tools/04-shell-completion.md b/docs/09-tools/04-shell-completion.md new file mode 100644 index 00000000..1d1bedde --- /dev/null +++ b/docs/09-tools/04-shell-completion.md @@ -0,0 +1,49 @@ +# Command Line Completion + +As a `serverpod` user, you can enable command line completion in most shells. The Serverpod CLI supports completion through [Carapace](https://carapace.sh/), which provides tab-completion for commands, options, and their values in bash, zsh, fish, PowerShell, and more. + +## Installing completion + +### Prerequisites + +Install Carapace for your platform: + +```bash +brew install carapace +``` + +For other platforms, see the [Carapace installation guide](https://carapace-sh.github.io/carapace-bin/install.html). + +### Enable Carapace completion for Serverpod + +#### Bash + +Install the completion spec and enable Carapace in your shell: + +```bash +serverpod completion install --tool carapace +source <(carapace serverpod) +``` + +To make this permanent, add `source <(carapace _carapace)` to your `~/.bashrc`. + +#### Zsh + +Install the completion spec and enable Carapace in your shell: + +```bash +serverpod completion install --tool carapace +zstyle ':completion:*' format $'\e[2;37mCompleting %d\e[m' +source <(carapace serverpod) +``` + +To make this permanent, add the following to your `~/.zshrc`: + +```bash +zstyle ':completion:*' format $'\e[2;37mCompleting %d\e[m' +source <(carapace _carapace) +``` + +#### Other shells + +Carapace supports fish, PowerShell, elvish, and more. After installing the completion spec with `serverpod completion install --tool carapace`, see the [Carapace setup documentation](https://carapace-sh.github.io/carapace-bin/setup.html) for instructions specific to your shell. From ee990e692d50eb0837541ee6d7d24807e62984e4 Mon Sep 17 00:00:00 2001 From: Preston Date: Thu, 19 Feb 2026 15:36:44 -0600 Subject: [PATCH 2/4] Updated title to be proper case. --- docs/09-tools/04-shell-completion.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/09-tools/04-shell-completion.md b/docs/09-tools/04-shell-completion.md index 1d1bedde..2fc572fb 100644 --- a/docs/09-tools/04-shell-completion.md +++ b/docs/09-tools/04-shell-completion.md @@ -1,4 +1,4 @@ -# Command Line Completion +# Command line completion As a `serverpod` user, you can enable command line completion in most shells. The Serverpod CLI supports completion through [Carapace](https://carapace.sh/), which provides tab-completion for commands, options, and their values in bash, zsh, fish, PowerShell, and more. From a509e640af2e4f3cf86be6ae036dbad3a334392f Mon Sep 17 00:00:00 2001 From: Preston Date: Thu, 19 Feb 2026 15:47:09 -0600 Subject: [PATCH 3/4] Fixed some inconsistent explanations. --- docs/09-tools/04-shell-completion.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/09-tools/04-shell-completion.md b/docs/09-tools/04-shell-completion.md index 2fc572fb..a08f10d5 100644 --- a/docs/09-tools/04-shell-completion.md +++ b/docs/09-tools/04-shell-completion.md @@ -18,32 +18,37 @@ For other platforms, see the [Carapace installation guide](https://carapace-sh.g #### Bash -Install the completion spec and enable Carapace in your shell: +Install the completion spec: ```bash serverpod completion install --tool carapace -source <(carapace serverpod) ``` -To make this permanent, add `source <(carapace _carapace)` to your `~/.bashrc`. +Then add the following to your `~/.bashrc` to enable Carapace: + +```bash +source <(carapace _carapace) +``` + +Restart your shell or run `source ~/.bashrc` to apply. #### Zsh -Install the completion spec and enable Carapace in your shell: +Install the completion spec: ```bash serverpod completion install --tool carapace -zstyle ':completion:*' format $'\e[2;37mCompleting %d\e[m' -source <(carapace serverpod) ``` -To make this permanent, add the following to your `~/.zshrc`: +Then add the following to your `~/.zshrc` to enable Carapace: ```bash zstyle ':completion:*' format $'\e[2;37mCompleting %d\e[m' source <(carapace _carapace) ``` +Restart your shell or run `source ~/.zshrc` to apply. + #### Other shells Carapace supports fish, PowerShell, elvish, and more. After installing the completion spec with `serverpod completion install --tool carapace`, see the [Carapace setup documentation](https://carapace-sh.github.io/carapace-bin/setup.html) for instructions specific to your shell. From 69840d41fae8d467f78d2550d85b529bb1ea616b Mon Sep 17 00:00:00 2001 From: Preston Date: Fri, 20 Feb 2026 07:58:22 -0600 Subject: [PATCH 4/4] Added completely section. Added linux and windows examples. --- docs/09-tools/04-shell-completion.md | 33 +++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/docs/09-tools/04-shell-completion.md b/docs/09-tools/04-shell-completion.md index a08f10d5..09d7281e 100644 --- a/docs/09-tools/04-shell-completion.md +++ b/docs/09-tools/04-shell-completion.md @@ -6,12 +6,26 @@ As a `serverpod` user, you can enable command line completion in most shells. Th ### Prerequisites -Install Carapace for your platform: +Install [Carapace](https://carapace.sh/) for your platform: + +**macOS:** ```bash brew install carapace ``` +**Ubuntu/Debian:** + +```bash +sudo apt install carapace-bin +``` + +**Windows:** + +```powershell +winget install carapace +``` + For other platforms, see the [Carapace installation guide](https://carapace-sh.github.io/carapace-bin/install.html). ### Enable Carapace completion for Serverpod @@ -52,3 +66,20 @@ Restart your shell or run `source ~/.zshrc` to apply. #### Other shells Carapace supports fish, PowerShell, elvish, and more. After installing the completion spec with `serverpod completion install --tool carapace`, see the [Carapace setup documentation](https://carapace-sh.github.io/carapace-bin/setup.html) for instructions specific to your shell. + +## Alternative: Completely + +The Serverpod CLI also supports [Completely](https://github.com/bashly-framework/completely), a lightweight alternative to Carapace that supports bash and zsh. Unlike Carapace, Completely does not require a separate tool running in your shell — it generates a standalone bash completion script. + +To generate a Completely spec and create a completion script: + +```bash +serverpod completion generate --tool completely -f serverpod.yaml +completely generate serverpod.yaml serverpod.bash +``` + +Then source the generated script in your shell config (e.g., `source /path/to/serverpod.bash` in `~/.bashrc` or `~/.zshrc`). + +:::note +Carapace is the recommended tool as it supports a wider range of shells and comes with a pre-built completion spec that can be installed directly with `serverpod completion install`. Completely requires generating and processing the script manually. +:::