Document missing commands (#1542)

RELEASE_NOTES=n/a

Signed-off-by: Dominik Schulz <[email protected]>

docs/commands/edit.md

@@ -0,0 +1,31 @@
+# `edit` command
+
+The `edit` command loads a new or existing secret into your `$EDITOR` (default: `vim`)
+and saves the resulting content in the password store. It will attempt to create secure
+temporary directory (depending on the OS) and will warn if insecure editor configuration
+(currently only `vim`) is detected.
+
+Native `gopass` MIME secrets are syntax checked and invalid encodings are rejected.
+Any other type of secret is accepted as is.
+
+`gopass` will honor templates when creating a new entry.
+
+## Synopsis
+
+```
+$ gopass edit entry
+$ gopass edit -e /bin/nano entry
+$ EDITOR=/bin/nano gopass edit entry
+```
+
+## Modes of operation
+
+* Create a new secret
+* Edit an existing secret
+
+## Flags
+
+Flag | Aliases | Description
+---- | ------- | -----------
+`--editor` | `-e` | Specify the path to an editor. Must accept the filename as it's first argument.
+`--create` | `-c` | Create a new secret. Note: This is a no-op. You can create a new secret with `edit` with or without `-c`.

docs/commands/fsck.md

@@ -0,0 +1,22 @@
+# `fsck` command
+
+`gopass` can check integrity of it's password stores with the `fsck` command.
+It will ensure proper file and directory permissions as well as proper
+recipient coverage (on supported crypto backends, only).
+
+## Synopsis
+
+```
+$ gopass fsck
+```
+
+## Modes of operation
+
+* Check the entire password store, incl. all mounts
+* Check only the specified mount
+
+## Flags
+
+Flag | Aliases | Description
+---- | ------- | -----------
+`--decrypt` | | Decrypt and reencrypt all secrets. WARNING: This will update all secrets to the native `gopass` MIME format. This might be incompatible with other password store clients.

docs/commands/gopass.md

@@ -0,0 +1,21 @@
+# `gopass` command
+
+Calling `gopass` without any command argument is a common entry point and
+has two different modes.
+
+## Synopsis
+
+```
+$ gopass
+$ gopass entry
+```
+
+## Modes of operation
+
+* Invoked without any arguments `gopass` will start an interactive REPL shell. This includes zero-setup command completion and passphrase caching (for non-GPG backends).
+* Invoked with one argument it will perform a (fuzzy) search and display a list of matches or the secret directly (if exactly one match).
+* Invoked with two arguments it will do search and if there is a match display the named key.
+
+## Flags
+
+Note: `gopass` intentionally does not support any flags. If you need to use any flag consider using `gopass show` instead.

docs/commands/grep.md

@@ -0,0 +1,21 @@
+# `grep` command
+
+The `grep` command works like the Unix `grep` tool. It decrypts all secrets
+and performs a substring or regexp match on the given pattern.
+
+## Synopsis
+
+```
+$ gopass grep foobar
+```
+
+## Modes of operations
+
+* Search for the given pattern in all secrets
+
+## Flags
+
+None.
+Flag | Aliases | Description
+---- | ------- | -----------
+`--regexp` | | Parse the pattern as a RE2 regular expression.

docs/commands/history.md

@@ -0,0 +1,17 @@
+# `history` command
+
+The `gopass history` command will show all revisions of a given secret.
+
+## Synopsis
+
+```
+$ gopass history entry
+```
+
+## Modes of operation
+
+* Display all revisions of the given secret.
+
+## Flags
+
+None.

docs/commands/mount.md

@@ -0,0 +1,25 @@
+# `mount` commands
+
+The `mount` commands allow managing mounted substores. This is one of the
+distinctive core features of `gopass` and we aim making working with substores
+as seamless as possible.
+
+Instead of support for encrypting different parts of a store for different
+recipients we instead encourage users to mount different stores - each
+encrypted to a uniform set of recipients - into a semless virtual tree structure.
+
+This feature is modeled after standard POSIX mount semantics.
+
+## Synopsis
+
+```
+$ gopass mounts
+$ gopass mounts add mount/point /path/to/store
+$ gopass mounts remove mount/point
+```
+
+## Modes of operation
+
+* Add a new mount
+* List existing mounts
+* Remove an existing mount

docs/commands/otp.md

@@ -0,0 +1,18 @@
+# `otp` command
+
+The `otp` command generates TOTP tokens from an OTP URL (`otpauth://`).
+The command tries to parse the password and the totp fields as an OTP URL.
+
+Note: HTOP is currently not supported.
+
+## Modes of operation
+
+* Generate the current TOTP token from a valid OTP URL
+
+## Flags
+
+Flag | Aliases | Description
+---- | ------- | -----------
+`--clip` | `-c` | Copy the time-based token into the clipboard.
+`--qr` | `-q` | Write QR code to file.
+`--password` | `-o` | Only display the token. For use in scripts.

docs/commands/pwgen.md

@@ -0,0 +1,20 @@
+# `pwgen` command
+
+The `pwgen` command implements a subset of the features of the Unix/Linux
+`pwgen` command line tool. It aims to eventually support most of the `pwgen`
+flags and mirror it's behaviour. It is mainly implemented as a curtosy for
+Windows users.
+
+## Modes of operation
+
+* Generate a few dozen random passwords
+
+## Flags
+
+Flag | Aliases | Description
+---- | ------- | -----------
+`--no-numerals` | `-0` | Do not include numerals in the generated passwords.
+`--one-per-line` | `-1` | Print one password per line.
+`--xkcd` | `-x` | Use multiple random english words combined to a password.
+`--sep` | `--xs` | Word separator for multi-word passwords.
+`--lang` | `--xl` | Language to generate password from. Currently only supports english (en, default) and german (de).

docs/commands/recipients.md

@@ -0,0 +1,34 @@
+# `recipients` commands
+
+The set of `recipients` commands allow managing public keys that are able to
+decrypt a given password store.
+
+These commands are one of the more unique `gopass` features and we aim to
+make working with this as seamless as possible.
+
+## Synopsis
+
+```
+$ gopass recipients
+$ gopass recipients add
+$ gopass recipients remove
+```
+
+## Modes of operation
+
+* List all existing recipients, per mount: `gopass recipients`
+* Add/Authorize a new public key to decrypt a store (mount): `gopass recipients add`
+* Remove/Deuathorize an existing public key from a store (mount): `gopass recipients remove`
+
+## Flags
+
+Flag | Aliases | Description
+`--store` | | Store to operate on.
+`--force` | | Do not ask for confirmation.
+
+## Important Remarks
+
+WARNING: Removing a recipient can only ever work for new or changed secrets.
+When a recipient is removed they will still be able to access anything that
+they used to have access to. As a logical consequence one **should** change
+all secrets when removing a recipient.

docs/commands/templates.md

@@ -0,0 +1,68 @@
+# `templates` commands
+
+The template support is one of the more unique `gopass` features. It allows
+password stores to define templates that will automatically apply to any new
+secret create at or below the template path. For example this can be useful
+to generate a new email password and the salted hash at the same time. Or a
+PostgreSQL password with the custom salted hash. This is certainly a feature
+that's not used very often, but if used corretly it can greatly reduce the
+toil of some common operations.
+
+## Synopsis
+
+```
+$ gopass templates
+$ gopass templates show template
+$ gopass templates edit template
+$ gopass templates remove template
+```
+
+## Flags
+
+None.
+
+## Examples
+
+### Compute the salted hash for the password
+
+```
+Password: {{ .Content }}
+SSHA256: {{ .Content | ssha256 }}
+```
+
+### Compute the SQL statements to create a new PostgreSQL user
+
+```
+{{ .Content }}
+---
+sql:  |
+  CREATE ROLE {{ .Name }} LOGIN PASSWORD '{{ .Content }}';
+  GRANT {{ .Name }} TO {{ .Name }};
+  ALTER USER {{ .Name }} SET search_path = '{{ .Name }}';
+```
+
+## Template functions
+
+Function | Example | Description
+-------- | ------- | -----------
+`md5sum` | `{{ .Content \| md5sum }}` | Calculate the hex md5sum of the input.
+`sha1sum` | `{{ .Content \| sha1sum }}` | Calculate the hex sha1sum of the input.
+`md5crypt` | `{{ .Content \| md5crypt }}` | Calculate the md5crypt of the input.
+`ssha` | `{{ .Content \| ssha }}` | Calculate the salted SHA-1 of the input.
+`ssha256` | `{{ .Content \| ssha256 }}` | Calculate the salted SHA-256 of the input.
+`ssha512` | `{{ .Content \| ssha512 }}` | Calculate the slated SHA-512 of the input.
+`get` | `{{ get "foo/bar" }}` | Insert the full secret.
+`getpw` | `{{ getpw "foo/bar" }}` | Insert the value of the password field from the given secret.
+`getval` | `{{ getval "foo/bar" "baz" }}` | Insert the value of the named filed from the given secret.
+
+## Template variables
+
+Note: These examples assume being evaluated for the secret `foo/bar/baz` and
+the generated password `VerySecure`.
+
+Name | Example | Description
+---- | ------- | -----------
+`Dir` | `foo/bar` | The directory containing the secret.
+`Path` | `foo/bar/baz` | The path or full name of the secret.
+`Name` | `baz` | The last element of the path or short name of the secret.
+`Content` | `VerySecure` | The generated password.

docs/commands/update.md

@@ -0,0 +1,19 @@
+# `update` command
+
+The `update` command will attempt to auto-update `gopass` by downloading the
+latest release from GitHub. It performs several pre-flight checks in order to
+determine if the binary can be updated or not (e.g. if managed by a package
+manager).
+
+## Synopsis
+
+```
+$ gopass update
+$ gopass update --pre
+```
+
+## Flags
+
+Flag | Description
+---- | -----------
+`--pre` | Update to pre-releases / release candidates (default: `false`).

internal/action/commands.go

@@ -742,15 +742,6 @@ func (s *Action) GetCommands() []*cli.Command {
 						},
 					},
 				},
-				{
-					Name:  "update",
-					Usage: "Recompute the saved recipient list checksums",
-					Description: "" +
-						"This command will recompute the saved recipient checksum" +
-						"and save them to the config.",
-					Before: s.Initialized,
-					Action: s.RecipientsUpdate,
-				},
 			},
 		},
 		{

internal/action/pwgen/commands.go

@@ -29,14 +29,14 @@ func GetCommands() []*cli.Command {
 					Usage:   "Use multiple random english words combined to a password. By default, space is used as separator and all words are lowercase",
 				},
 				&cli.StringFlag{
-					Name:    "xkcdsep",
-					Aliases: []string{"xs"},
+					Name:    "sep",
+					Aliases: []string{"xkcdsep", "xs"},
 					Usage:   "Word separator for generated xkcd style password. If no separator is specified, the words are combined without spaces/separator and the first character of words is capitalised. This flag implies -xkcd",
 					Value:   " ",
 				},
 				&cli.StringFlag{
-					Name:    "xkcdlang",
-					Aliases: []string{"xl"},
+					Name:    "lang",
+					Aliases: []string{"xkcdlang", "xl"},
 					Usage:   "Language to generate password from, currently de (german) and en (english, default) are supported",
 					Value:   "en",
 				},

internal/action/pwgen/pwgen.go

@@ -44,7 +44,7 @@ func Pwgen(c *cli.Context) error {
 
 func xkcdGen(c *cli.Context, num int) error {
 	for i := 0; i < num; i++ {
-		s, err := xkcdgen.RandomLengthDelim(4, c.String("xkcdsep"), c.String("xkcdlang"))
+		s, err := xkcdgen.RandomLengthDelim(4, c.String("sep"), c.String("lang"))
 		if err != nil {
 			return err
 		}