Install the BWS CLI and store your first secret

Lesson outcome

You will have the BWS CLI installed on your local machine and be able to store and retrieve secrets from the terminal.

Why this matters in an agency

This lesson is your first encounter with the terminal — the text-based interface where Claude Code lives. Everything you do in this course beyond Obsidian happens in the terminal. Getting comfortable here is not optional, but it is also not hard. You type a command, press Enter, and something happens. That is the entire model.

The specific skill you are building — retrieving secrets from the command line — is the same pattern you will use on your VPS later. Tools that need a database password or an API key will pull it from BWS at runtime instead of reading it from a file someone pasted it into six months ago.

Inputs, tools, and prerequisites

Your Bitwarden organization with Secrets Manager enabled and the test secret you created in the previous lesson. A willingness to open a terminal for the first time.

Step-by-step walkthrough

Open your terminal

On Mac, open the Terminal application. You can find it in Applications > Utilities > Terminal, or press Cmd+Space and type "Terminal." Mac's built-in Terminal is all you need.

On Windows, you will use PowerShell inside Windows Terminal. These are two separate things: PowerShell is the shell (the program that interprets your commands), and Windows Terminal is the window that runs it. Together they give you a modern, capable terminal on Windows.

Windows setup: Install Windows Terminal and PowerShell 7

Windows comes with an older version of PowerShell (5.1) built in, but you want PowerShell 7 — it is faster, more capable, and supports modern tools like Claude Code and SSH natively. Here is how to set it up:

1. Install Windows Terminal — Open the Microsoft Store app, search for "Windows Terminal," and install it. If you are on Windows 11, it may already be installed.
2. Install PowerShell 7 — Open the Windows Terminal you just installed. In it, type:

```
winget install Microsoft.PowerShell
```

This installs PowerShell 7 alongside the old version. They do not conflict.

3. Set PowerShell 7 as the default — In Windows Terminal, click the dropdown arrow next to the tab bar and open Settings. Under "Startup," change the default profile to "PowerShell" (the PowerShell 7 entry, not "Windows PowerShell" which is the old 5.1). Save.
4. Install a good font (recommended) — The default terminal font works, but a Nerd Font adds icons and better readability. In PowerShell 7, run:

```
winget install JanDeDobbeleer.OhMyPosh
oh-my-posh font install CascadiaCode
```

Then in Windows Terminal Settings, go to Profiles > Defaults > Appearance and set the font face to CaskaydiaCove NF. This font is designed for terminals and includes the special characters that developer tools use.

5. Optional polish — If you want a professional-looking terminal with a styled prompt and file icons, add these to your PowerShell profile. First, install the modules:

```
Install-Module -Name Terminal-Icons -Repository PSGallery -Force -Scope CurrentUser
```

Then open your profile for editing:

```
notepad $PROFILE
```

Add these lines:

```
oh-my-posh init pwsh --config "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/catppuccin_mocha.omp.json" | Invoke-Expression
Import-Module Terminal-Icons
Set-PSReadLineOption -PredictionSource History
Set-PSReadLineOption -PredictionViewStyle ListView
```

Save and close. Restart Windows Terminal. You will see a styled prompt with git status, icons on file listings, and command history predictions as you type. This is entirely optional — the tools work without it — but it makes the terminal significantly more pleasant to use daily.

The companion download for this lesson includes a complete Windows Terminal setup guide with all the details.

Close Windows Terminal and reopen it. You should now be in PowerShell 7 by default. You can verify by checking the version:

```
$PSVersionTable.PSVersion
```

The Major version should be 7 or higher.

Your first command

You should see a window with a blinking cursor waiting for you to type something. This is the terminal. Everything you type here is a command, and pressing Enter runs it.

Try something harmless first. Type the following and press Enter:

```
echo "Hello from my terminal"
```

You should see "Hello from my terminal" printed back. That confirms the terminal is working. You just ran your first command.

Create a machine account and access token

Go back to Bitwarden in your browser. Navigate to your organization's Secrets Manager section. Find the Machine Accounts area and create a new machine account. Name it "local-machine" or "my-laptop."

Grant this machine account access to the project you created in the previous lesson. This tells BWS that this machine account is allowed to read and write secrets in that project.

Now generate an access token for this machine account. Bitwarden will show you the token once. Copy it immediately and paste it into a temporary note — you need it in the next step. The access token is a long string. Treat it like a password.

Install the BWS CLI

The BWS CLI is a small program that lets you interact with Bitwarden Secrets Manager from the terminal. The installation method depends on your operating system.

On Mac with Homebrew:

```
brew install bitwarden/bws/bws
```

If you do not have Homebrew, go to the Bitwarden Secrets Manager CLI documentation page and download the binary for Mac directly.

On Windows, download the BWS CLI binary from the Bitwarden Secrets Manager CLI documentation page. Extract the file and place it in a directory that is in your system PATH, or add its location to PATH.

On both Mac and Windows, if you prefer npm (you will install npm in the next module anyway):

```
npm install -g @bitwarden/bws-cli
```

After installation, verify it works:

```
bws --version
```

You should see a version number. If you see "command not found" or an error, the installation did not complete correctly. Check that the bws binary is in your system PATH.

Authenticate and retrieve your test secret

Set your access token as an environment variable so the BWS CLI can authenticate.

On Mac:

```
export BWS_ACCESS_TOKEN="paste-your-access-token-here"
```

On Windows PowerShell:

```
$env:BWS_ACCESS_TOKEN = "paste-your-access-token-here"
```

Replace the placeholder with the actual access token you copied from Bitwarden.

Now list the secrets available to this machine account:

```
bws secret list
```

You should see your test secret in the output — the one you created in the web interface. The output is JSON showing the secret's name, ID, and value.

To retrieve a specific secret by its ID:

```
bws secret get
```

Replace with the ID from the list output. You should see the full secret including its value.

Store a new secret from the CLI

Create a new secret directly from the terminal:

```
bws secret create --project-id "cli-test-secret" "created-from-terminal"
```

Replace with your project's ID (visible in the list output or in the Bitwarden web UI). This creates a new secret called "cli-test-secret" with the value "created-from-terminal."

Go back to the Bitwarden web interface and confirm the new secret appears in your project. You just stored a secret from the command line and verified it in the web UI. That round-trip — CLI to cloud to web — is the pattern you will use throughout this course.

Clean up the environment variable

The access token you set with export only lasts until you close the terminal. When you close the terminal window, it disappears. On your VPS later, you will store this token persistently using a secure method. For now, know that closing the terminal clears it.

Failure modes and verification checks

The most common failure is a typo in the access token. BWS authentication errors usually mean the token was pasted incorrectly — copy it again carefully. Another common issue is PATH problems — the terminal cannot find the bws command because the binary is not in a directory the system searches. If bws --version does not work, confirm where the binary was installed and add that location to your PATH.

Verification: run bws secret list and confirm it returns your test secret with the correct value. If it does, BWS is working correctly.

Implementation checklist

• Open your terminal for the first time.
• Create a machine account in Bitwarden Secrets Manager.
• Generate an access token for the machine account.
• Install the BWS CLI.
• Set the access token as an environment variable.
• List and retrieve your test secret.
• Create a new secret from the CLI.
• Verify the new secret appears in the Bitwarden web interface.

Immediate next action

Close your terminal and move to the next module. You will install Claude Code next.

Exercise

Without looking back at the lesson, open a new terminal window and try to retrieve your test secret from BWS. You will need to set the access token environment variable again (it was cleared when you closed the terminal). If you can retrieve the secret successfully on the second try without re-reading the instructions, you understand the workflow. If you get stuck, re-read the steps and try once more. The goal is not memorization. The goal is understanding the pattern: set the token, run the command, get the result.