1 71c704e3 2023-01-16 op .\" Copyright (c) 2022, 2023 Omar Polo <op@omarpolo.com>
  2 e346be82 2022-06-29 op .\"
  3 e346be82 2022-06-29 op .\" Permission to use, copy, modify, and distribute this software for any
  4 e346be82 2022-06-29 op .\" purpose with or without fee is hereby granted, provided that the above
  5 e346be82 2022-06-29 op .\" copyright notice and this permission notice appear in all copies.
  6 e346be82 2022-06-29 op .\"
  7 e346be82 2022-06-29 op .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  8 e346be82 2022-06-29 op .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  9 e346be82 2022-06-29 op .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 10 e346be82 2022-06-29 op .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 11 e346be82 2022-06-29 op .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 12 e346be82 2022-06-29 op .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 13 e346be82 2022-06-29 op .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 14 847f206c 2023-01-23 op .Dd January 23, 2023
 15 e346be82 2022-06-29 op .Dt PLASS 1
 16 e346be82 2022-06-29 op .Os
 17 e346be82 2022-06-29 op .Sh NAME
 18 e346be82 2022-06-29 op .Nm plass
 19 e346be82 2022-06-29 op .Nd manage passwords
 20 e346be82 2022-06-29 op .Sh SYNOPSIS
 21 e346be82 2022-06-29 op .Nm
 22 e346be82 2022-06-29 op .Op Fl h
 23 5a0f0861 2022-09-09 op .Ar command
 24 5a0f0861 2022-09-09 op .Op Ar argument ...
 25 e346be82 2022-06-29 op .Sh DESCRIPTION
 26 e346be82 2022-06-29 op .Nm
 27 86b0d4f5 2023-01-21 op is a password manager.
 28 86b0d4f5 2023-01-21 op Every password lives inside a
 29 86b0d4f5 2023-01-21 op .Xr gpg 1
 30 86b0d4f5 2023-01-21 op encrypted file somewhere inside
 31 86b0d4f5 2023-01-21 op .Pa ~/.password-store
 32 86b0d4f5 2023-01-21 op which is managed with the
 33 2a7970ee 2022-10-01 op .Xr got 1
 34 86b0d4f5 2023-01-21 op version control system to keep track of changes, recovery accidental
 35 86b0d4f5 2023-01-21 op overwrites and synchronize it across devices.
 36 2a7970ee 2022-10-01 op .Pp
 37 86b0d4f5 2023-01-21 op The options are as follows:
 38 b3b555d9 2022-10-05 op .Bl -tag -width Ds
 39 b3b555d9 2022-10-05 op .It Fl h
 40 b3b555d9 2022-10-05 op Display usage information and exit immediately.
 41 b3b555d9 2022-10-05 op .El
 42 b3b555d9 2022-10-05 op .Pp
 43 e346be82 2022-06-29 op The following commands are available:
 44 e346be82 2022-06-29 op .Bl -tag -width Ds
 45 e346be82 2022-06-29 op .It Cm cat Ar entries ...
 46 2a7970ee 2022-10-01 op Decrypt and print the content of
 47 5a0f0861 2022-09-09 op .Ar entries
 48 5a0f0861 2022-09-09 op in the given order.
 49 8ce01796 2023-01-11 op .It Cm edit Ar entry
 50 86b0d4f5 2023-01-21 op Interactively modify the content of the given
 51 8ce01796 2023-01-11 op .Ar entry
 52 86b0d4f5 2023-01-21 op with an editor.
 53 e346be82 2022-06-29 op .It Cm find Op Ar pattern
 54 2a7970ee 2022-10-01 op Print the entries of the store one per line, optionally filtered by
 55 91fcc6e3 2023-01-11 op the case-insensitive
 56 e346be82 2022-06-29 op .Ar pattern .
 57 e346be82 2022-06-29 op .It Cm mv Ar from Ar to
 58 e346be82 2022-06-29 op Rename a password entry, doesn't work with directories.
 59 e346be82 2022-06-29 op .Ar from
 60 2a7970ee 2022-10-01 op must exist and
 61 e346be82 2022-06-29 op .Ar to
 62 e346be82 2022-06-29 op mustn't.
 63 e346be82 2022-06-29 op .It Cm rm Ar entries ...
 64 e346be82 2022-06-29 op Remove the given
 65 e346be82 2022-06-29 op .Ar entries
 66 e346be82 2022-06-29 op from the store.
 67 e346be82 2022-06-29 op .It Cm tee Oo Fl q Oc Ar entry
 68 78859d14 2022-10-20 op Persist the data read from standard input into the store under the given
 69 e346be82 2022-06-29 op .Ar entry
 70 d49216fe 2023-01-11 op name and then print it again on the standard output unless the
 71 e346be82 2022-06-29 op .Fl q
 72 5a0f0861 2022-09-09 op option is given.
 73 e346be82 2022-06-29 op .El
 74 86b0d4f5 2023-01-21 op .Pp
 75 86b0d4f5 2023-01-21 op Password entries can be referenced using the path relative to the
 76 86b0d4f5 2023-01-21 op store directory.
 77 86b0d4f5 2023-01-21 op The file extension
 78 86b0d4f5 2023-01-21 op .Dq \&.gpg
 79 86b0d4f5 2023-01-21 op can be omitted.
 80 e346be82 2022-06-29 op .Sh ENVIRONMENT
 81 e346be82 2022-06-29 op .Bl -tag -width Ds
 82 e346be82 2022-06-29 op .It Ev PLASS_GPG
 83 e346be82 2022-06-29 op Path to the
 84 5a0f0861 2022-09-09 op .Xr gpg 1
 85 e346be82 2022-06-29 op executable.
 86 e346be82 2022-06-29 op .It Ev PLASS_STORE
 87 c992a1e9 2022-12-03 op Alternative path to the password store directory tree.
 88 8ce01796 2023-01-11 op .It Ev VISUAL , Ev EDITOR
 89 8ce01796 2023-01-11 op The editor spawned by
 90 8ce01796 2023-01-11 op .Nm
 91 8ce01796 2023-01-11 op .Cm edit .
 92 8ce01796 2023-01-11 op If not set, the
 93 8ce01796 2023-01-11 op .Xr ed 1
 94 8ce01796 2023-01-11 op text editor will be used in order to given it the attention
 95 8ce01796 2023-01-11 op it deserves.
 96 e346be82 2022-06-29 op .El
 97 e346be82 2022-06-29 op .Sh FILES
 98 e346be82 2022-06-29 op .Bl -tag -width Ds
 99 e346be82 2022-06-29 op .It Pa ~/.password-store
100 329651fd 2023-01-11 op Default password store.
101 e346be82 2022-06-29 op .It Pa ~/.password-store/.gpg-id
102 2a7970ee 2022-10-01 op File containing the GPG recipient used to encrypt the passwords.
103 e346be82 2022-06-29 op .El
104 254b1ceb 2022-10-02 op .Sh EXIT STATUS
105 5576f8c2 2022-10-05 op .Ex -std
106 2a7970ee 2022-10-01 op .Sh EXAMPLES
107 2a7970ee 2022-10-01 op A got repository and password store can be initialized as follows:
108 2a7970ee 2022-10-01 op .Bd -literal -offset indent
109 2a7970ee 2022-10-01 op $ mkdir ~/.password-store
110 2a7970ee 2022-10-01 op $ echo foo@example.com > ~/.password-store/.gpg-id
111 2a7970ee 2022-10-01 op $ gotadmin init ~/git/pass.git
112 2a7970ee 2022-10-01 op $ got import -r ~/git/pass.git -m 'initial import' ~/.password-store
113 2a7970ee 2022-10-01 op $ got checkout -E ~/git/pass.git ~/.password-store
114 2a7970ee 2022-10-01 op .Ed
115 2a7970ee 2022-10-01 op .Pp
116 2a7970ee 2022-10-01 op see
117 2a7970ee 2022-10-01 op .Xr got 1
118 2a7970ee 2022-10-01 op for more information.
119 2a7970ee 2022-10-01 op .Pp
120 2a7970ee 2022-10-01 op To migrate from
121 2a7970ee 2022-10-01 op .Xr pass 1 ,
122 2a7970ee 2022-10-01 op delete
123 2a7970ee 2022-10-01 op .Pa ~/.password-store
124 2a7970ee 2022-10-01 op and check out it again using
125 2a7970ee 2022-10-01 op .Xr got 1 .
126 2a7970ee 2022-10-01 op .Pp
127 c992a1e9 2022-12-03 op Generate a random password and save it to the clipboard:
128 2a7970ee 2022-10-01 op .Bd -literal -offset indent
129 c992a1e9 2022-12-03 op $ pwg | plass tee entry/name | xsel -b
130 2a7970ee 2022-10-01 op .Ed
131 5ed185dd 2022-10-02 op .Pp
132 86b0d4f5 2023-01-21 op Generate a TOTP token using the secret stored in the password store:
133 86b0d4f5 2023-01-21 op .Bd -literal -offset indent
134 86b0d4f5 2023-01-21 op $ plass cat 2fa/codeberg/op | totp
135 86b0d4f5 2023-01-21 op 722524
136 86b0d4f5 2023-01-21 op .Ed
137 86b0d4f5 2023-01-21 op .Pp
138 847f206c 2023-01-23 op Interactively edit the contents of
139 847f206c 2023-01-23 op .Pa entry/name
140 847f206c 2023-01-23 op with
141 847f206c 2023-01-23 op .Xr mg 1 :
142 847f206c 2023-01-23 op .Bd -literal -offset indent
143 847f206c 2023-01-23 op $ env VISUAL=mg plass edit entry/name
144 847f206c 2023-01-23 op .Ed
145 847f206c 2023-01-23 op .Pp
146 5ed185dd 2022-10-02 op Display the entries matching
147 5ed185dd 2022-10-02 op .Sq key
148 5ed185dd 2022-10-02 op arranged comfortably for reading in a terminal window:
149 5ed185dd 2022-10-02 op .Bd -literal -offset indent
150 5ed185dd 2022-10-02 op $ plass find key | rs
151 5ed185dd 2022-10-02 op .Ed
152 7c62b772 2022-12-03 op .Pp
153 7c62b772 2022-12-03 op Enable tab-completion of
154 7c62b772 2022-12-03 op .Nm
155 7c62b772 2022-12-03 op command names and entries in
156 7c62b772 2022-12-03 op .Xr ksh 1 :
157 7c62b772 2022-12-03 op .Bd -literal -offset indent
158 8ce01796 2023-01-11 op $ set -A complete_plass_1 -- cat edit find mv rm tee
159 7c62b772 2022-12-03 op $ set -A complete_plass -- $(plass find)
160 7c62b772 2022-12-03 op .Ed
161 2a7970ee 2022-10-01 op .Sh SEE ALSO
162 2a7970ee 2022-10-01 op .Xr got 1 ,
163 2a7970ee 2022-10-01 op .Xr gpg 1 ,
164 86b0d4f5 2023-01-21 op .Xr pwg 1 ,
165 86b0d4f5 2023-01-21 op .Xr totp 1
166 2a7970ee 2022-10-01 op .Sh HISTORY
167 e346be82 2022-06-29 op .Nm
168 e346be82 2022-06-29 op was heavily influenced by
169 e346be82 2022-06-29 op .Xr pass 1
170 2a7970ee 2022-10-01 op in the design, but it's a different implementation that prioritizes ease
171 2a7970ee 2022-10-01 op of use and composability.
172 e346be82 2022-06-29 op .Sh AUTHORS
173 e346be82 2022-06-29 op .An -nosplit
174 e346be82 2022-06-29 op The
175 e346be82 2022-06-29 op .Nm
176 e346be82 2022-06-29 op utility was written by
177 e346be82 2022-06-29 op .An Omar Polo Aq Mt op@omarpolo.com .
178 e346be82 2022-06-29 op .Sh CAVEATS
179 e346be82 2022-06-29 op .Nm
180 e346be82 2022-06-29 op .Cm find
181 e346be82 2022-06-29 op output format isn't designed to handle files containing newlines.
182 e346be82 2022-06-29 op Use
183 e346be82 2022-06-29 op .Xr find 1
184 e346be82 2022-06-29 op .Fl print0
185 e346be82 2022-06-29 op or similar if it's a concern.
186 e346be82 2022-06-29 op .Pp
187 2a7970ee 2022-10-01 op .Nm
188 2a7970ee 2022-10-01 op .Cm mv
189 2a7970ee 2022-10-01 op is not able to move directory trees, only file entries.
190 2a7970ee 2022-10-01 op .Pp
191 d49216fe 2023-01-11 op There isn't an
192 e346be82 2022-06-29 op .Cm init
193 e346be82 2022-06-29 op sub-command, the store initialization must be performed manually.