Add examples and CLI readme

Signed-off-by: jolheiser <john.olheiser@gmail.com>

.woodpecker.yml

@@ -17,9 +17,6 @@ pipeline:
     commands:
       - GOOS="windows" go build ./cmd/spectre
       - GOOS="linux" go build ./cmd/spectre
-    when:
-      event: [ push, tag ]
-      branch: main
 
   release-main:
     image: jolheiser/drone-gitea-main:latest

cmd/spectre/README.md

@@ -0,0 +1,33 @@
+# Spectre CLI
+
+All flags can be supplied as environment variables starting with `SPECTRE_*`
+
+e.g. `--username` -> `SPECTRE_USERNAME`
+
+### Usage
+
+```text
+spectre [FLAGS] [site]
+  -counter int
+        counter (default 1)
+  -scope value
+        scope
+  -scoper string
+        scoper base (default "com.lyndir.masterpassword")
+  -secret string
+        secret
+  -template value
+        template
+  -username string
+        username
+```
+
+### Example
+
+```shell
+export SPECTRE_USERNAME="Robert Lee Mitchell"
+export SPECTRE_SECRET="banana colored duckling"
+
+spectre masterpasswordapp.com
+# Jejr5[RepuSosp
+```

cmd/spectre/main.go

@@ -11,9 +11,12 @@ import (
 
 func main() {
 	fs := flag.NewFlagSet("spectre", flag.ExitOnError)
+	fs.Usage = func() {
+		fmt.Fprintln(fs.Output(), "spectre [FLAGS] [site]")
+		fs.PrintDefaults()
+	}
 	usernameFlag := fs.String("username", "", "username")
 	secretFlag := fs.String("secret", "", "secret")
-	siteFlag := fs.String("site", "", "site")
 	counterFlag := fs.Int("counter", 1, "counter")
 	scoperFlag := fs.String("scoper", "com.lyndir.masterpassword", "scoper base")
 	scopeFlag := spectre.Authentication
@@ -38,7 +41,7 @@ func main() {
 		templateFlag = scopeFlag.DefaultTemplate()
 	}
 
-	if *usernameFlag == "" || *secretFlag == "" || *siteFlag == "" {
+	if *usernameFlag == "" || *secretFlag == "" || len(os.Args) < 2 {
 		panic("username, secret, and site are required")
 	}
 
@@ -49,7 +52,7 @@ func main() {
 		panic(err)
 	}
 
-	pw := s.Site(*siteFlag,
+	pw := s.Site(os.Args[1],
 		spectre.WithScope(scopeFlag),
 		spectre.WithTemplate(templateFlag),
 		spectre.WithCounter(*counterFlag),

spectre_test.go

@@ -3,6 +3,7 @@ package spectre_test
 import (
 	_ "embed"
 	"encoding/xml"
+	"fmt"
 	"strconv"
 	"testing"
 
@@ -53,18 +54,34 @@ func TestSpectre(t *testing.T) {
 }
 
 // From the website sanity check
-func TestSanity(t *testing.T) {
+func Example() {
 	s, err := spectre.New("Robert Lee Mitchell", "banana colored duckling")
 	if err != nil {
-		t.Logf("failed sanity check: %v", err)
+		panic(err)
-		t.FailNow()
 	}
 
 	pw := s.Site("masterpasswordapp.com")
-	if pw != "Jejr5[RepuSosp" {
+	fmt.Println(pw)
-		t.Log("failed sanity check")
+	// Output: Jejr5[RepuSosp
-		t.FailNow()
 }
+
+// Example with options
+func Example_second() {
+	scoper := spectre.SimpleScoper{
+		Key: "com.jojodev.jolheiser",
+	}
+	s, err := spectre.New("Robert Lee Mitchell", "banana colored duckling", spectre.WithScoper(scoper))
+	if err != nil {
+		panic(err)
+	}
+
+	pw := s.Site("jojodev.com",
+		spectre.WithScope(spectre.Identification),
+		spectre.WithTemplate(spectre.Maximum),
+		spectre.WithCounter(2), // Password was leaked, so increment counter (example)
+	)
+	fmt.Println(pw)
+	// Output: Ig^JIcxD!*)TbefJBi6-
 }
 
 //go:embed spectre_tests.xml