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