From e8ae0a649180eb93176b4410b96225a1b50e03b4 Mon Sep 17 00:00:00 2001
From: holly sparkles <sparkles@holly.sh>
Date: Thu, 29 Feb 2024 23:12:41 +0100
Subject: [PATCH] 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.
---
 README.md | 122 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 121 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 3ac3fbb..1d846ec 100644
--- a/README.md
+++ b/README.md
@@ -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!
--
libgit2 1.7.2