Welcome to little lamb

Code » ssp » commit 1cdbf30

doc: Add examples

author Olivier Brunel
2023-09-19 07:58:58 UTC
committer Olivier Brunel
2023-09-20 11:07:37 UTC
parent 9235cd738e2782c9dfbf45733cec6efaa0bddff3

doc: Add examples

src/doc/ssp-add.1.md +14 -0
src/doc/ssp-edit.1.md +14 -0
src/doc/ssp-export.1.md +6 -0
src/doc/ssp-get.1.md +28 -0
src/doc/ssp-import.1.md +12 -0
src/doc/ssp-list.1.md +13 -0
src/doc/ssp-remove.1.md +12 -0
src/doc/ssp-rename.1.md +19 -0
src/doc/ssp-show.1.md +6 -0

diff --git a/src/doc/ssp-add.1.md b/src/doc/ssp-add.1.md
index e1ed7f1..7a478e8 100644
--- a/src/doc/ssp-add.1.md
+++ b/src/doc/ssp-add.1.md
@@ -45,6 +45,20 @@ set with *--algo*, the hashing algorithm is SHA1.
 :: Set entry to be time-based (TOTP) with a precision of `SECS` seconds. Valid
 :: values are from 10 to 59 (both included); Default to 30.
 
+# EXAMPLES
+
+To create a new entry named "test" using the ASCII string "12345678901234567890"
+as actual secret :
+
+    $ ssp add test GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ
+
+
+To create a new time-based entry named "foobar" with a 1 minute (60s) precision,
+using SHA256 as hashing algorithm and SECRET= as (base32-encoded) secret :
+
+    $ ssp a --algo sha256 -t60 foobar SECRET=
+
+
 # SEE ALSO
 
 [ssp-edit](1), [ssp-remove](1)
diff --git a/src/doc/ssp-edit.1.md b/src/doc/ssp-edit.1.md
index b9a04e1..ef28e98 100644
--- a/src/doc/ssp-edit.1.md
+++ b/src/doc/ssp-edit.1.md
@@ -47,6 +47,20 @@ at a time.
 :: Set entry to be time-based (TOTP) with a precision of `SECS` seconds. Valid
 :: values are from 10 to 59 (both included); Default to 30.
 
+# EXAMPLES
+
+Edit entry "foo" to reset its counter to 42 (i.e. next time an OTP is generated
+it will be using 42 a counter value) :
+
+    $ ssp edit -e foo -c42
+
+
+Edit entry "bar" to have a time precision of 60 seconds and generate OTP of 8
+digits, also adding a small comment :
+
+    $ ssp ed -e bar --time=60 -d8 -C '"This is a comment.\n\nOver multiple lines."'
+
+
 # SEE ALSO
 
 [ssp-add](1), [ssp-rename](1), [ssp-remove](1)
diff --git a/src/doc/ssp-export.1.md b/src/doc/ssp-export.1.md
index 93ff160..0da7ef4 100644
--- a/src/doc/ssp-export.1.md
+++ b/src/doc/ssp-export.1.md
@@ -33,6 +33,12 @@ Refer to [ssp-list](1) for more on pattern matching.
 : *-C*, *--no-comments*
 :: Do not export entries' comments.
 
+# EXAMPLE
+
+To export all entries whose name start with "web-" into a file `web-entries` :
+
+    $ ssp exp 'web-*' > web-entries
+
 # SEE ALSO
 
 [ssp-list](1), [ssp-show](1)
diff --git a/src/doc/ssp-get.1.md b/src/doc/ssp-get.1.md
index fad401e..3817801 100644
--- a/src/doc/ssp-get.1.md
+++ b/src/doc/ssp-get.1.md
@@ -80,3 +80,31 @@ use general option *--quiet*.
 :: Return a time-based password (TOTP) using a precision of `SECS` seconds.
 :: Valid values are from 10 to 59 (both included); Default to 30 unless *--entry*
 :: is used.
+
+# EXAMPLES
+
+To get an OTP from entry "foo" but using a counter value of 23 /without/
+updating the database, without the "HOTP: " prefix (i.e. only write the actual
+OTP on stdout) :
+
+    $ ssp -q get -e foo -C23
+
+
+To get an OTP using GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ as (base32-encoded) secret
+and a counter of 5 :
+
+    $ ssp get -s GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ -c5
+
+
+To get a TOTP from entry named "time" using Unix timestamp 1234567890 (i.e.
+2009-02-13 23:31:30) :
+
+    $ ssp g -e time -T1234567890
+
+
+To get an 8-digit TOTP using GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ as secret and the
+current time minus 55 minutes : \
+(/refer to your shell's documentation for actual syntax/)
+
+    $ ssp get -s GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ -td8
+        --use-time=$(date --date="55 minutes ago" +%s)
diff --git a/src/doc/ssp-import.1.md b/src/doc/ssp-import.1.md
index 2d923b6..9edeafb 100644
--- a/src/doc/ssp-import.1.md
+++ b/src/doc/ssp-import.1.md
@@ -29,6 +29,18 @@ command; Refer to [ssp-show](1) (option *--format*) for more.
 !
 ! Refer to your shell's manual for actual syntax.
 
+# EXAMPLE
+
+Import entries from file `myentries` :
+
+    $ ssp import myentries
+
+Import into `new.ssp` all entries names whose name start with "web-" : \
+(/refer to your shell's documentation for actual syntax/)
+
+    $ ssp -D new.ssp import <(ssp export 'web-*')
+
+
 # SEE ALSO
 
 [ssp-export](1)
diff --git a/src/doc/ssp-list.1.md b/src/doc/ssp-list.1.md
index f4fc45e..2697183 100644
--- a/src/doc/ssp-list.1.md
+++ b/src/doc/ssp-list.1.md
@@ -67,6 +67,19 @@ shown using *--details*.
 :: Note that entries' names are always written within double-quotes (and escaped
 :: as per escaping rules described for arguments described in [ssp](1)).
 
+# EXAMPLES
+
+List all entries whose name contains "foo" - showing details and secrets but not
+comments - from database `test.ssp` :
+
+    $ ssp -D test.ssp l -SC '*foo*'
+
+
+List all entries as a colon-separated list :
+
+    $ ssp list -s:
+
+
 # SEE ALSO
 
 [ssp-export](1), [ssp-show](1)
diff --git a/src/doc/ssp-remove.1.md b/src/doc/ssp-remove.1.md
index df6a22a..5bc6add 100644
--- a/src/doc/ssp-remove.1.md
+++ b/src/doc/ssp-remove.1.md
@@ -18,6 +18,18 @@ The *remove* command allows to remove existing entry `ENTRY` from the database.
 ! As a safe-guard, unless general option *--quiet* was used, the entry will be
 ! shown before its removal, including its secret.
 
+# EXAMPLES
+
+Remove entry named "foo" :
+
+    $ ssp rem foo
+
+
+Remove entry named "foo" without showing the entry on stdout :
+
+    $ ssp --quiet rem foo
+
+
 # SEE ALSO
 
 [ssp-edit](1), [ssp-add](1)
diff --git a/src/doc/ssp-rename.1.md b/src/doc/ssp-rename.1.md
index faab2d7..f7abb99 100644
--- a/src/doc/ssp-rename.1.md
+++ b/src/doc/ssp-rename.1.md
@@ -15,6 +15,25 @@ The *rename* command allows to rename  existing entry `ENTRY` to `NEWNAME`.
 
 <inc show-entry.md>
 
+# EXAMPLES
+
+Rename entry "foo" to "foobar" :
+
+    $ spp ren foo foobar
+
+
+Rename entry "André" (encoded in latin1) to "André" (encoded in UTF8), assuming
+your current shell/locale is UTF8) :
+
+    $ ssp rename '"Andr\xe9"' André
+
+! INFO:
+! Note that in the above example, prior to renaming *ssp* would show the entry
+! as `"Andr\xe9"` when using e.g. the `list` command.
+! Such a case of "bad encoding" could potentially happen e.g. when using *ssp*
+! on a different system (using a different locale) than when the entry was added.
+
+
 # SEE ALSO
 
 [ssp-edit](1)
diff --git a/src/doc/ssp-show.1.md b/src/doc/ssp-show.1.md
index 968fcc2..623a8b5 100644
--- a/src/doc/ssp-show.1.md
+++ b/src/doc/ssp-show.1.md
@@ -80,6 +80,12 @@ are the list of names/settings :
 :: Comments associated with the entry, within double-quotes and escaped as per
 :: the escaping rules described for arguments in [ssp](1).
 
+# EXAMPLE
+
+Show entry "foobar" including its secret (but not its comments) :
+
+    $ ssp show --no-comm -S foobar
+
 # SEE ALSO
 
 [ssp-list](1), [ssp-export](1)