From f37be97c2e4b4f6fe4a5666a972f6e6535806dab Mon Sep 17 00:00:00 2001 From: Munif Tanjim Date: Tue, 26 May 2020 20:02:09 +0600 Subject: [PATCH 1/2] Add CLI shell completion documentation --- _articles/miscellaneous/cli.md | 35 ++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/_articles/miscellaneous/cli.md b/_articles/miscellaneous/cli.md index 1d4d8a48c..71672ad78 100644 --- a/_articles/miscellaneous/cli.md +++ b/_articles/miscellaneous/cli.md @@ -43,6 +43,8 @@ Bitwarden provides a powerful, full-featured command-line interface (CLI) tool t - [Config](#config) - [Update](#update) - [Version](#version) +- [Shell Completion](#shell-completion) + - [ZSH](#zsh) - [Working with JSON](#working-with-json) - [Self-signed Certificates](#self-signed-certificates) - [Source Code](#source-code) @@ -401,6 +403,39 @@ The `--version` option allows you to check which version the CLI you are current bw --version ``` +## Shell Completion + +Bitwarded CLI comes with support for shell completion. It can generate shell completion scripts that you can use to enable completion for `bw` in your shell. + +### ZSH + +You can enable `bw` completion for ZSH using various methods. A few of them are mentioned below: + +**vanilla (.zshrc)**: + +Add the following line in your `.zshrc` file: + +```shell +eval "$(bw completion --shell zsh); compdef _bw bw;" +``` + +**vanilla (vendor-completions)**: + +Run the following command: + +```shell +bw completion --shell zsh | sudo tee /usr/share/zsh/vendor-completions/_bw +``` + +[**zinit**](https://github.com/zdharma/zinit): + +Run the following commands: + +```shell +bw completion --shell zsh > ~/.local/share/zsh/completions/_bw +zinit creinstall ~/.local/share/zsh/completions +``` + ## Working with JSON Commands in the CLI will either return a JSON string or a simple string such as a URL, GUID, or message. When you need to parse or manipulate JSON input/output with the CLI we recommend using the [`jq` command-line tool](https://stedolan.github.io/jq/){:target="_blank"}. From 758db80b738442bab977959868a7e518891eb93f Mon Sep 17 00:00:00 2001 From: Kyle Spearrin Date: Tue, 26 May 2020 10:06:48 -0400 Subject: [PATCH 2/2] Update cli.md --- _articles/miscellaneous/cli.md | 63 +++++++++++++++++----------------- 1 file changed, 32 insertions(+), 31 deletions(-) diff --git a/_articles/miscellaneous/cli.md b/_articles/miscellaneous/cli.md index 71672ad78..3ed06a5ac 100644 --- a/_articles/miscellaneous/cli.md +++ b/_articles/miscellaneous/cli.md @@ -43,10 +43,10 @@ Bitwarden provides a powerful, full-featured command-line interface (CLI) tool t - [Config](#config) - [Update](#update) - [Version](#version) -- [Shell Completion](#shell-completion) - - [ZSH](#zsh) - [Working with JSON](#working-with-json) - [Self-signed Certificates](#self-signed-certificates) +- [Shell Completion](#shell-completion) + - [ZSH](#zsh) - [Source Code](#source-code) - [Appendix](#appendix) - [Templates](#templates) @@ -403,6 +403,33 @@ The `--version` option allows you to check which version the CLI you are current bw --version ``` +## Working with JSON + +Commands in the CLI will either return a JSON string or a simple string such as a URL, GUID, or message. When you need to parse or manipulate JSON input/output with the CLI we recommend using the [`jq` command-line tool](https://stedolan.github.io/jq/){:target="_blank"}. + + # Get a login item's password + bw get item google | jq '.login.password' + + # Create a new folder from a template + bw get template folder | jq '.name = "My Folder"' | bw encode | bw create folder + + # Update an existing folder's name + bw get folder dadc91e0-dcda-4bc2-8cd6-52100027c782 | jq '.name = "Updated Folder"' | \ + bw encode | bw edit folder dadc91e0-dcda-4bc2-8cd6-52100027c782 + +## Self-signed Certificates + +If your self-hosted Bitwarden server exposes as self-signed TLS certificate, specify the Node.js environment variable [`NODE_EXTRA_CA_CERTS`](https://nodejs.org/api/cli.html#cli_node_extra_ca_certs_file): + +{% icon fa-linux %} {% icon fa-apple %} Bash + + export NODE_EXTRA_CA_CERTS="absolute/path/to/your/certificates.pem" + +{% icon fa-windows %} PowerShell + + $env:NODE_EXTRA_CA_CERTS="absolute/path/to/your/certificates.pem" + + ## Shell Completion Bitwarded CLI comes with support for shell completion. It can generate shell completion scripts that you can use to enable completion for `bw` in your shell. @@ -415,7 +442,7 @@ You can enable `bw` completion for ZSH using various methods. A few of them are Add the following line in your `.zshrc` file: -```shell +``` eval "$(bw completion --shell zsh); compdef _bw bw;" ``` @@ -423,7 +450,7 @@ eval "$(bw completion --shell zsh); compdef _bw bw;" Run the following command: -```shell +``` bw completion --shell zsh | sudo tee /usr/share/zsh/vendor-completions/_bw ``` @@ -431,37 +458,11 @@ bw completion --shell zsh | sudo tee /usr/share/zsh/vendor-completions/_bw Run the following commands: -```shell +``` bw completion --shell zsh > ~/.local/share/zsh/completions/_bw zinit creinstall ~/.local/share/zsh/completions ``` -## Working with JSON - -Commands in the CLI will either return a JSON string or a simple string such as a URL, GUID, or message. When you need to parse or manipulate JSON input/output with the CLI we recommend using the [`jq` command-line tool](https://stedolan.github.io/jq/){:target="_blank"}. - - # Get a login item's password - bw get item google | jq '.login.password' - - # Create a new folder from a template - bw get template folder | jq '.name = "My Folder"' | bw encode | bw create folder - - # Update an existing folder's name - bw get folder dadc91e0-dcda-4bc2-8cd6-52100027c782 | jq '.name = "Updated Folder"' | \ - bw encode | bw edit folder dadc91e0-dcda-4bc2-8cd6-52100027c782 - -## Self-signed Certificates - -If your self-hosted Bitwarden server exposes as self-signed TLS certificate, specify the Node.js environment variable [`NODE_EXTRA_CA_CERTS`](https://nodejs.org/api/cli.html#cli_node_extra_ca_certs_file): - -{% icon fa-linux %} {% icon fa-apple %} Bash - - export NODE_EXTRA_CA_CERTS="absolute/path/to/your/certificates.pem" - -{% icon fa-windows %} PowerShell - - $env:NODE_EXTRA_CA_CERTS="absolute/path/to/your/certificates.pem" - ## Source Code As with everything here at Bitwarden, the CLI is fully open source and hosted on GitHub at .