Improving documentation

README.md

@@ -35,7 +35,7 @@ cumbersome.
 Each bitagent process is capable of storing only one secret. This keeps the code
 simple, which helps keep it performant and reduces the chance of errors.
 
-Installation & usage
+Installation
 ---
 
 To install bitagent, use the standard `go install` process.
@@ -46,10 +46,18 @@ git clone https://github.com/mjslabs/bitagent.git && cd bitagent
 go install
 ```
 
+Usage
+---
+
 The easiest way to work with bitagent is by making a wrapper script for your
 use case. See [examples](examples), which includes such a script for use with
 the Bitwarden CLI. Below are the instructions for working with bitagent
-manually, or when creating your own wrapper script.
+manually, or when creating your own wrapper script. If you're only interested in
+the Bitwarden use case, see the comments at the top of the
+[bw](examples/bw) example file.
+
+If you're interested in running bitagent manually, or creating your own wrapper,
+read on.
 
 First, launch bitagent using your system's preferred method of backgrounding a
 process, e.g.
@@ -74,6 +82,18 @@ To retrieve the secret, use `G`.
 echo "G" | nc -U ~/.bitagent.sock -N
 ```
 
+Full example showing the storage of the string `mysecret`, then retrieving it.
+
+```shell
+$ echo Pmysecret | nc -U ~/.bitagent.sock -N
+$ echo G | nc -U ~/.bitagent.sock -N
+mysecret
+```
+
+Your wrapper script should understand the output of the command you're proxying,
+parsing the output for whatever token you're looking to store, then use `nc` or
+something similar to store and retrieve the secret as needed.
+
 Caveats
 ---
 
@@ -83,7 +103,7 @@ out or included in core dumps. This has not been fully vetted by the authors of
 bitagent.  
 
 bitagent defaults to storing up to a 256 byte secret. This is tunable at the
-top of [main.go](main.go). This should be made to be dynamic.
+top of [bitagent.go](cmd/bitagent.go). This should be made dynamic.
 
 The only thing stopping someone from accessing your secret in bitagent is the
 permissions on the socket file. These default to a sane value, but there are

examples/bw

@@ -1,37 +1,45 @@
 #!/usr/bin/env bash
 
-# Proxy commands for the bitwarden CLI, intercepting them to get or set a
-# session token for seamless use between shells and other programs.
+# This script will proxy commands for the bitwarden CLI, intercepting them to
+# get or set a # session token for seamless use between shells and other programs.
 # Make sure this script is in your $PATH, so you can simply run 'bw' like you
 # normally would.
 
 # If you have a $HOME/bin dir that is at the front of your $PATH, you should be
 # able to use this as an install method:
 # curl https://raw.githubusercontent.com/mjslabs/bitagent/master/examples/bw > $HOME/bin/bw && chmod 0755 $HOME/bin/bw
 
-# Installation of the bitwarden CLI
+# You will want to make sure that $bwcmd below is the full path to the real
+# bitwarden cli. The default is 'bwcli' stored in ~/bin
+
+# Installation of the real bitwarden CLI
 bwcmd="${HOME}/bin/bwcli"
 # Default socket location
 basock="${HOME}/.bitagent.sock"
-# This assumes you've run a `go install`
+# This assumes you've run a `go install` to install bitagent
 bitagent="${GOBIN:-${HOME}/go/bin}/bitagent $basock"
 
+# If our socket doesn't exist then run bitagent
 if [[ ! -e $basock ]]; then
   $bitagent 1>/dev/null & disown
 fi
 
+# If runninig 'bw unlock' or 'bw login', expect the session key to be output on success
 if [[ $1 == "unlock" || $1 == "login" ]]; then
   unlockOut=$($bwcmd $1)
   <<< $unlockOut grep -q BW_SESSION
   if [[ $? == "0" ]]; then
     echo "$1 successful"
+    # Store the key in bitagent
     echo "P"$(<<< $unlockOut tr -d '\n' | sed -e 's/^.*BW_SESSION="\(.*\)".*$/\1/') | nc -U $basock -N
   else
     echo "$1 failed"
     echo $unlockOut
   fi
   exit
 else
+  # We're running some bitwarden command that isn't login or unlock,
+  # so set BW_SESSION using the secret in bitagent, then run the bw cli
   export BW_SESSION="$(echo G | nc -U $basock -N)"
   if [[ $BW_SESSION == "" ]]; then
     # Avoids "Session key is invalid." being sent to the terminal