docs: update README
i had an opportunity to share this project and realised that i don't
have any good documentation outside of the man pages.
Diff
README.md | 122 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 121 insertions(+), 1 deletion(-)
@@ -2,4 +2,124 @@
Add SSH keys to ssh-agent using [bitwarden-cli](https://bitwarden.com/help/cli/). Written in Rust.
This is a port of [bitwarden-ssh-agent](https://github.com/joaojacome/bitwarden-ssh-agent), which is written in Python.
\ No newline at end of file
This is a port of [bitwarden-ssh-agent](https://github.com/joaojacome/bitwarden-ssh-agent), which is written in Python.
## Table of Contents
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Cargo (automatic)](#cargo-automatic)
- [From Source (manually)](#from-source-manually)
- [Bitwarden Setup](#bitwarden-setup)
- [Usage](#usage)
- [Manual](#manual)
- [Contributing](#contributing)
- [License](#license)
- [Troubleshooting](#troubleshooting)
- [Stuck in a login loop](#stuck-in-a-login-loop)
- [I use Windows](#i-use-windows)
## Getting Started
Before you begin, ensure that you have the Bitwarden CLI, the Rust toolchain, and `cargo` installed. If you haven't installed them yet, you can do so by following the instructions provided on the following sites:
- [Bitwarden CLI](https://bitwarden.com/help/cli/)
- [Install Rust](https://www.rust-lang.org/learn/get-started)
Once you have these installed, you can proceed with setting up and running the project.
### Installation
#### Cargo (automatic)
```shell
cargo install --git https://git.holly.sh/bitwarden-ssh-agent.git
```
#### From Source (manually)
Clone the repository and build:
```shell
git clone https://git.holly.sh/bitwarden-ssh-agent.git
cd bitwarden-ssh-agent
cargo build --release
```
The `bitwarden-ssh-agent` binary will be found in the `target/release` directory. Run it directly from there or copy it to `/usr/bin/`.
### Bitwarden Setup
There is some setup required in Bitwarden itself. The steps are:
1. Create a folder to store the keys in. Name it `ssh-agent`.
2. Create a new login entry, name it, and save it.
3. Edit the entry that you just made and add your SSH private key as an attachment.
4. Create a new entry with the following custom fields:
- passphrase (type: hidden)
- private (type: text)
5. Save the entry and add your other keys (if applicable).
**Notes:**
- The value of the `passphrase` field is the passphrase to the private key. If there is no passphrase, you can remove the field.
- The value of the `private` field is the file name of the SSH private key that you attached.
- The names of the folder and custom fields can be customized. Run `bitwarden-ssh-agent -h` or consult the [manual](#manual) for more information.
If you haven't done so yet, setup the Bitwarden CLI using:
```shell
bw login
```
and follow the instructions to set your `BW_SESSION` environment variable or add it to your shell.
## Usage
If all of the above requirements are satisfied, register your keys with:
```shell
bitwarden-ssh-agent
```
Happy logging in :)
## Manual
You can build the manual (`man`) page for this project using `[pandoc](https://pandoc.org/)`.
From the project root:
```bash
pandoc --standalone --to man ./doc/man/bw-ssh-agent.1.md -o ./target/bw-ssh-agent.1
```
To see your manual, use:
```bash
man -l ./target/bw-ssh-agent.1
```
To install the manual to the system, consult your distribution's owners manual and place it in the `man1` directory. On my machine, that is `/usr/share/man/man1/`.
## Contributing
Patches are welcome via [`git-send-email`](https://git-scm.com/docs/git-send-email).
## License
bitwarden-ssh-agent is licensed under the [AGPL 3.0](LICENSE).
## Troubleshooting
### Stuck in a login loop
**Symptom:**
Attempting to login fails because of a login loop. This means that your `BW_SESSION` has expired.
**Solution:**
Run `bw logout` and then `bw login` and get a new `BW_SESSION` token.
### I use Windows
I can't help, sorry!
