Skip to content

Commit d7289b1

Browse files
author
TheJoeIaut
committed
Split the build and test docs out of the README
The README had grown into a single page covering everything from what the plugin does to how to run a Vaultwarden container, which buried the two things a user actually needs: how to install it and how to use it. Building and Tests move to BUILDING.md and TESTING.md unchanged. What is left is rewritten around the user path - a requirements table, an installation sequence that starts with configuring the Bitwarden CLI, and a per-action usage guide covering the unlock credential sources and their precedence, the load-then-search item picker, and what each Selected Info option types. Notes that the published 1.0.0 release predates this year's work, and that the Master Password unlock option reaches bw as a command line argument.
1 parent f25b202 commit d7289b1

3 files changed

Lines changed: 207 additions & 103 deletions

File tree

‎BUILDING.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Building
2+
3+
The project targets `net10.0` and uses BarRaider's
4+
[StreamDeck-Tools](https://github.com/BarRaider/streamdeck-tools) v7. You need the
5+
[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) - the Desktop Runtime
6+
that users install is not enough to compile.
7+
8+
```bash
9+
dotnet build BitwardenCLI/BitwardenStreamdeckPlugin.csproj -c Release
10+
```
11+
12+
The build drops a ready-to-use plugin folder at
13+
`BitwardenCLI/bin/Release/com.thejoeiaut.bitwarden.sdPlugin/`. Copy it into your host's
14+
plugin directory (on Windows, `%APPDATA%\Elgato\StreamDeck\Plugins\`, with Stream Deck
15+
closed) to test it locally.
16+
17+
## Self-contained builds
18+
19+
To produce a build that carries its own runtime, publish self-contained into a
20+
`.sdPlugin` folder and zip that folder:
21+
22+
```bash
23+
dotnet publish BitwardenCLI/BitwardenStreamdeckPlugin.csproj -c Release -r win-x64 --self-contained true -o out/com.thejoeiaut.bitwarden.sdPlugin
24+
```
25+
26+
Swap `-r win-x64` for `linux-x64` or `osx-arm64` to build for the other platforms.
27+
Always pass `-o` when publishing so the RID-specific output does not overwrite the
28+
plain `dotnet build` output folder.
29+
30+
> Prefer `dotnet publish -r <rid>` over a plain `dotnet build` when you want something to
31+
> ship or install. Since the plugin gained Linux and macOS targets, a plain build carries
32+
> every platform's SkiaSharp natives and comes to roughly 180 MB; publishing for a single
33+
> runtime keeps it near 16 MB.
34+
35+
## Installing your build locally (Windows)
36+
37+
```powershell
38+
powershell -ExecutionPolicy Bypass -File tools/install-local.ps1
39+
```
40+
41+
That publishes, stops Stream Deck, replaces
42+
`%APPDATA%\Elgato\StreamDeck\Plugins\com.thejoeiaut.bitwarden.sdPlugin`, starts Stream Deck
43+
again and prints the plugin's log so you can see it registered.
44+
45+
Stream Deck holds the plugin's executable open, so it has to be stopped for the files to be
46+
replaced - there is no way around the restart. Stream Deck usually runs at a higher
47+
integrity level than an ordinary shell, so stopping it outright needs an elevated prompt;
48+
otherwise the script asks you to quit it from its tray icon and waits (`-WaitMinutes`,
49+
10 by default). Pass `-SkipBuild` to install the last publish again, or `-NoRelaunch` to
50+
leave Stream Deck closed.
51+
52+
## See also
53+
54+
- [TESTING.md](TESTING.md) - running the unit and integration suites
55+
- [README.md](README.md) - installation and usage

‎README.md‎

Lines changed: 100 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -10,34 +10,16 @@ This unofficial Plugin allows interaction with the Bitwarden CLI. Actions allow
1010
| Get Item Information | Types a stored username, password or TOTP at the cursor | yes |
1111
| Generate Password | Generates a password or passphrase and types it at the cursor | no |
1212

13-
### Generate Password
14-
15-
Exposes the same options as the Bitwarden generator, backed by `bw generate`:
16-
17-
- **Password**: length, which character types to include (`A-Z`, `a-z`, `0-9`, symbols),
18-
minimum counts for numbers and symbols, and avoiding ambiguous characters.
19-
- **Passphrase**: word count, separator, title casing and including a number.
20-
21-
Because generation happens entirely in the CLI, this action works on a locked vault - no
22-
Unlock needed first.
23-
24-
Unchecking every character type is refused rather than quietly falling back to a default,
25-
so you can never end up with a weaker password than the one you configured.
26-
27-
## Instructions
28-
1. Download the Bitwarden CLI (https://bitwarden.com/help/cli/#download-and-install)
29-
2. (optional) Configure your CLI (https://bitwarden.com/help/cli/#config)
30-
3. Login (https://bitwarden.com/help/cli/#log-in)
31-
4. Unlock the vault via CLI or configure Unlock Action in plugin
32-
5. Configure Get Information Task
33-
6. (optional) Lock Vault via CLI or configure Lock Action in plugin
34-
3513
## Requirements
3614

37-
The plugin runs on **.NET 10** and requires the
38-
[.NET 10 Desktop Runtime](https://dotnet.microsoft.com/download/dotnet/10.0) to be
39-
installed. If you would rather ship a build that does not need the runtime, see the
40-
self-contained publish commands below.
15+
| You need | Why |
16+
| --- | --- |
17+
| [Bitwarden CLI](https://bitwarden.com/help/cli/#download-and-install) (`bw` on `PATH`) | Every action shells out to it; the plugin never talks to Bitwarden directly |
18+
| [.NET 10 Desktop Runtime](https://dotnet.microsoft.com/download/dotnet/10.0) | The plugin runs on **.NET 10** |
19+
| Stream Deck 4.9 or newer | Minimum host version in the plugin manifest |
20+
21+
A self-contained build carries its own runtime and needs no .NET install - see
22+
[BUILDING.md](BUILDING.md).
4123

4224
Typing a credential into the focused window needs a platform helper:
4325

@@ -52,108 +34,123 @@ On Linux the helper is picked at runtime: `ydotool` when `WAYLAND_DISPLAY` is se
5234
otherwise `xdotool`. Credentials are handed to these tools over stdin, never as command
5335
line arguments, so they cannot be read out of the process list.
5436

55-
## Platform support
37+
## Installation
5638

57-
Elgato's own Stream Deck software runs on **Windows and macOS only**, and the plugin
58-
manifest has no Linux platform value. To use this plugin on Linux you need a third party
59-
host such as [OpenDeck](https://github.com/nekename/OpenDeck), which runs plugins built
60-
for the original Stream Deck SDK. OpenDeck can also run the Windows build under Wine, so
61-
a native Linux build is not strictly required.
39+
### 1. Set up the Bitwarden CLI
6240

63-
macOS and Linux are built and published successfully but have not been tested on real
64-
hardware.
41+
The plugin drives an already-configured `bw`, so do this first and confirm it works from
42+
a terminal before touching Stream Deck.
6543

66-
## Building
44+
1. [Download and install the CLI](https://bitwarden.com/help/cli/#download-and-install)
45+
and make sure `bw` is on your `PATH`.
46+
2. (optional) [Point it at your server](https://bitwarden.com/help/cli/#config) if you
47+
use Vaultwarden or a self-hosted Bitwarden: `bw config server https://vault.example.com`
48+
3. [Log in](https://bitwarden.com/help/cli/#log-in): `bw login`
6749

68-
The project targets `net10.0` and uses BarRaider's
69-
[StreamDeck-Tools](https://github.com/BarRaider/streamdeck-tools) v7.
50+
Logging in is a one-time step and survives reboots. Unlocking is separate, and is what
51+
the Unlock action does for you.
7052

71-
```bash
72-
dotnet build BitwardenCLI/BitwardenStreamdeckPlugin.csproj -c Release
73-
```
53+
### 2. Install the plugin
7454

75-
The build drops a ready-to-use plugin folder at
76-
`BitwardenCLI/bin/Release/com.thejoeiaut.bitwarden.sdPlugin/`. Copy it into your host's
77-
plugin directory (on Windows, `%APPDATA%\Elgato\StreamDeck\Plugins\`, with Stream Deck
78-
closed) to test it locally.
55+
**From a release.** Download `com.thejoeiaut.bitwarden.zip` from the
56+
[releases page](https://github.com/TheJoeIaut/Bitwarden-Streamdeck-Plugin/releases),
57+
unzip it, and double-click the `com.thejoeiaut.bitwarden.streamDeckPlugin` file inside.
58+
Stream Deck installs it and the actions appear under a **Bitwarden** category in the
59+
action list.
7960

80-
To produce a build that carries its own runtime, publish self-contained into a
81-
`.sdPlugin` folder and zip that folder:
61+
> The published 1.0.0 release dates from 2023 and does not include the newer work -
62+
> the Generate Password action, the searchable item picker, .NET 10 or the Linux and
63+
> macOS support. For those, build from source.
8264
83-
```bash
84-
dotnet publish BitwardenCLI/BitwardenStreamdeckPlugin.csproj -c Release -r win-x64 --self-contained true -o out/com.thejoeiaut.bitwarden.sdPlugin
85-
```
65+
**From source.** See [BUILDING.md](BUILDING.md). On Windows,
66+
`tools/install-local.ps1` publishes and installs in one step.
8667

87-
Swap `-r win-x64` for `linux-x64` or `osx-arm64` to build for the other platforms.
88-
Always pass `-o` when publishing so the RID-specific output does not overwrite the
89-
plain `dotnet build` output folder.
68+
### 3. Add the actions
9069

91-
> Prefer `dotnet publish -r <rid>` over a plain `dotnet build` when you want something to
92-
> ship or install. Since the plugin gained Linux and macOS targets, a plain build carries
93-
> every platform's SkiaSharp natives and comes to roughly 180 MB; publishing for a single
94-
> runtime keeps it near 16 MB.
70+
Drag **Unlock** and **Get Item Information** onto keys and configure them as described
71+
below. Both are under the Bitwarden category.
9572

96-
### Installing your build locally (Windows)
73+
## Usage
9774

98-
```powershell
99-
powershell -ExecutionPolicy Bypass -File tools/install-local.ps1
100-
```
75+
### Unlock
10176

102-
That publishes, stops Stream Deck, replaces
103-
`%APPDATA%\Elgato\StreamDeck\Plugins\com.thejoeiaut.bitwarden.sdPlugin`, starts Stream Deck
104-
again and prints the plugin's log so you can see it registered.
77+
Configure one credential source in the action's settings. If more than one is filled in,
78+
the first of these wins:
10579

106-
Stream Deck holds the plugin's executable open, so it has to be stopped for the files to be
107-
replaced - there is no way around the restart. Stream Deck usually runs at a higher
108-
integrity level than an ordinary shell, so stopping it outright needs an elevated prompt;
109-
otherwise the script asks you to quit it from its tray icon and waits (`-WaitMinutes`,
110-
10 by default). Pass `-SkipBuild` to install the last publish again, or `-NoRelaunch` to
111-
leave Stream Deck closed.
80+
1. **Master Password** - typed straight into the settings.
81+
2. **Environment Variable** - the *name* of a variable holding the password
82+
(`bw unlock --passwordenv`). The variable has to be visible to the Stream Deck
83+
process, so set it system-wide and restart Stream Deck.
84+
3. **Password File** - a file whose contents are the password
85+
(`bw unlock --passwordfile`).
11286

113-
## Tests
87+
> Prefer the environment variable or password file. The master password option is passed
88+
> to `bw` as a command line argument, which is visible in the process list while the
89+
> command runs, and Stream Deck stores action settings in plain text on disk either way.
11490
115-
Unit tests need nothing beyond the SDK and run everywhere:
91+
Pressing the key unlocks the vault and keeps the session key in memory for the other
92+
actions. The key shows a checkmark on success and a warning triangle if the CLI refused
93+
- a wrong password, or not being logged in.
11694

117-
```bash
118-
dotnet test BitwardenCLI.Tests/BitwardenCLI.Tests.csproj --filter "Category!=Integration"
119-
```
95+
The session lives in the plugin process, so it is gone when Stream Deck restarts. Press
96+
Unlock again after a restart; it does not need to be re-configured.
12097

121-
They cover the parsing of Bitwarden CLI output, the unlock argument selection, the
122-
keyboard layer's platform choices, and each action's success and failure paths against a
123-
stubbed CLI and keyboard.
98+
### Get Item Information
12499

125-
### Integration tests
100+
1. Unlock the vault first - the item list cannot be read from a locked vault.
101+
2. Press **Load** in the action's settings. That fetches your vault entries once. Each
102+
entry is labelled with its username in parentheses so several logins for the same site
103+
can be told apart.
104+
3. Type in **Selected Item** to search the loaded entries, and pick one. The X button
105+
clears the selection.
106+
4. Choose what the key types under **Selected Info**:
126107

127-
Two suites are marked `Category=Integration` and are excluded from the command above.
108+
| Selected Info | What gets typed |
109+
| --- | --- |
110+
| Username | The entry's username |
111+
| Password | The entry's password |
112+
| TOTP | The current six digit code, computed fresh on every press |
113+
| Username+Password | Username, then Tab, then password - fills a whole login form |
128114

129-
**Linux typing** (`LinuxKeyboardTests`) checks that `KeyboardTyper` really drives
130-
`xdotool` and that the characters arrive in the focused window. It needs Linux, an X
131-
display and `xdotool`, and skips anywhere else. The dev container and the CI Linux job
132-
both provide those.
115+
The list is loaded only when you press Load, not while you type, so pressing Load again
116+
is how you pick up entries added to your vault since.
133117

134-
**Vaultwarden end to end** (`VaultwardenE2ETests`) starts a throwaway Vaultwarden server
135-
with Testcontainers, registers an account, seeds a login entry and reads it back through
136-
the real `bw` CLI. It needs a container runtime (Docker or Podman), `bw` on `PATH`, and:
118+
TOTP asks the CLI for the current code rather than reading the stored seed, so what
119+
arrives at the cursor is a code a login form accepts.
137120

138-
```bash
139-
BW_E2E=1 dotnet test BitwardenCLI.Tests/BitwardenCLI.Tests.csproj --filter "Category=Integration"
140-
```
121+
### Generate Password
122+
123+
Needs no unlocked vault - generation happens entirely in the CLI. Exposes the same
124+
options as the Bitwarden generator, backed by `bw generate`:
125+
126+
- **Password**: length, which character types to include (`A-Z`, `a-z`, `0-9`, symbols),
127+
minimum counts for numbers and symbols, and avoiding ambiguous characters.
128+
- **Passphrase**: word count, separator (a single character, or the words `space` or
129+
`empty`), title casing and including a number.
141130

142-
> The `BW_E2E` opt-in exists because these tests run the real `bw` binary, which on a
143-
> developer machine is usually signed in to a real vault. Every invocation is given its
144-
> own throwaway `BITWARDENCLI_APPDATA_DIR`, so your login, server configuration and
145-
> session are never read or modified - but the tests stay opt-in regardless.
131+
**Output** decides where the result goes: typed at the cursor, copied to the clipboard,
132+
or both. Anything put on the clipboard stays there until something else replaces it.
146133

147-
There is no `bw register` command, so the fixture derives the account keys itself the way
148-
the official clients do (PBKDF2, HKDF, AES-CBC plus HMAC). If that were wrong the
149-
subsequent `bw login` would simply fail, so the end to end run validates it.
134+
Unchecking every character type is refused rather than quietly falling back to a default,
135+
so you can never end up with a weaker password than the one you configured.
136+
137+
### Lock
150138

151-
### Dev container
139+
No settings. Pressing the key locks the vault; the next Get press will fail until you
140+
unlock again.
141+
142+
## Platform support
143+
144+
Elgato's own Stream Deck software runs on **Windows and macOS only**, and the plugin
145+
manifest has no Linux platform value. To use this plugin on Linux you need a third party
146+
host such as [OpenDeck](https://github.com/nekename/OpenDeck), which runs plugins built
147+
for the original Stream Deck SDK. OpenDeck can also run the Windows build under Wine, so
148+
a native Linux build is not strictly required.
149+
150+
macOS and Linux are built and published successfully but have not been tested on real
151+
hardware.
152152

153-
`.devcontainer/` builds an image with the .NET 10 SDK, the Bitwarden CLI, `xdotool`,
154-
`xterm` and Xvfb, and starts a headless display on `:99`. Opening the repository in it
155-
lets the full suite - including both integration suites - run on Linux:
153+
## Development
156154

157-
```bash
158-
dotnet test BitwardenCLI.Tests/BitwardenCLI.Tests.csproj
159-
```
155+
- [BUILDING.md](BUILDING.md) - building, self-contained publishing, installing a local build
156+
- [TESTING.md](TESTING.md) - unit tests, the integration suites and the dev container

‎TESTING.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Tests
2+
3+
Unit tests need nothing beyond the SDK and run everywhere:
4+
5+
```bash
6+
dotnet test BitwardenCLI.Tests/BitwardenCLI.Tests.csproj --filter "Category!=Integration"
7+
```
8+
9+
They cover the parsing of Bitwarden CLI output, the unlock argument selection, the
10+
keyboard layer's platform choices, and each action's success and failure paths against a
11+
stubbed CLI and keyboard.
12+
13+
## Integration tests
14+
15+
Two suites are marked `Category=Integration` and are excluded from the command above.
16+
17+
**Linux typing** (`LinuxKeyboardTests`) checks that `KeyboardTyper` really drives
18+
`xdotool` and that the characters arrive in the focused window. It needs Linux, an X
19+
display and `xdotool`, and skips anywhere else. The dev container and the CI Linux job
20+
both provide those.
21+
22+
**Vaultwarden end to end** (`VaultwardenE2ETests`) starts a throwaway Vaultwarden server
23+
with Testcontainers, registers an account, seeds a login entry and reads it back through
24+
the real `bw` CLI. It needs a container runtime (Docker or Podman), `bw` on `PATH`, and:
25+
26+
```bash
27+
BW_E2E=1 dotnet test BitwardenCLI.Tests/BitwardenCLI.Tests.csproj --filter "Category=Integration"
28+
```
29+
30+
> The `BW_E2E` opt-in exists because these tests run the real `bw` binary, which on a
31+
> developer machine is usually signed in to a real vault. Every invocation is given its
32+
> own throwaway `BITWARDENCLI_APPDATA_DIR`, so your login, server configuration and
33+
> session are never read or modified - but the tests stay opt-in regardless.
34+
35+
There is no `bw register` command, so the fixture derives the account keys itself the way
36+
the official clients do (PBKDF2, HKDF, AES-CBC plus HMAC). If that were wrong the
37+
subsequent `bw login` would simply fail, so the end to end run validates it.
38+
39+
## Dev container
40+
41+
`.devcontainer/` builds an image with the .NET 10 SDK, the Bitwarden CLI, `xdotool`,
42+
`xterm` and Xvfb, and starts a headless display on `:99`. Opening the repository in it
43+
lets the full suite - including both integration suites - run on Linux:
44+
45+
```bash
46+
dotnet test BitwardenCLI.Tests/BitwardenCLI.Tests.csproj
47+
```
48+
49+
## See also
50+
51+
- [BUILDING.md](BUILDING.md) - building and publishing the plugin
52+
- [README.md](README.md) - installation and usage

0 commit comments

Comments
 (0)