Blob


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 to give it the attention it deserves.
95 .El
96 .Sh FILES
97 .Bl -tag -width Ds
98 .It Pa ~/.password-store
99 Default password store.
100 .It Pa ~/.password-store/.gpg-id
101 File containing the GPG recipient used to encrypt the passwords.
102 .El
103 .Sh EXIT STATUS
104 .Ex -std
105 .Sh EXAMPLES
106 A got repository and password store can be initialized as follows:
107 .Bd -literal -offset indent
108 $ mkdir ~/.password-store
109 $ echo foo@example.com > ~/.password-store/.gpg-id
110 $ gotadmin init ~/git/pass.git
111 $ got import -r ~/git/pass.git -m 'initial import' ~/.password-store
112 $ got checkout -E ~/git/pass.git ~/.password-store
113 .Ed
114 .Pp
115 see
116 .Xr got 1
117 for more information.
118 .Pp
119 To migrate from
120 .Xr pass 1 ,
121 delete
122 .Pa ~/.password-store
123 and check out it again using
124 .Xr got 1 .
125 .Pp
126 Generate a random password and save it to the clipboard:
127 .Bd -literal -offset indent
128 $ pwg | plass tee entry/name | xsel -b
129 .Ed
130 .Pp
131 Generate a TOTP token using the secret stored in the password store:
132 .Bd -literal -offset indent
133 $ plass cat 2fa/codeberg/op | totp
134 722524
135 .Ed
136 .Pp
137 Interactively edit the contents of
138 .Pa entry/name
139 with
140 .Xr mg 1 :
141 .Bd -literal -offset indent
142 $ env VISUAL=mg plass edit entry/name
143 .Ed
144 .Pp
145 Display the entries matching
146 .Sq key
147 arranged comfortably for reading in a terminal window:
148 .Bd -literal -offset indent
149 $ plass find key | rs
150 .Ed
151 .Pp
152 Enable tab-completion of
153 .Nm
154 command names and entries in
155 .Xr ksh 1 :
156 .Bd -literal -offset indent
157 $ set -A complete_plass_1 -- cat edit find mv rm tee
158 $ set -A complete_plass -- $(plass find)
159 .Ed
160 .Sh SEE ALSO
161 .Xr got 1 ,
162 .Xr gpg 1 ,
163 .Xr pwg 1 ,
164 .Xr totp 1
165 .Sh HISTORY
166 .Nm
167 was heavily influenced by
168 .Xr pass 1
169 in the design, but it's a different implementation that prioritizes ease
170 of use and composability.
171 .Sh AUTHORS
172 .An -nosplit
173 The
174 .Nm
175 utility was written by
176 .An Omar Polo Aq Mt op@omarpolo.com .
177 .Sh CAVEATS
178 .Nm
179 .Cm find
180 output format isn't designed to handle files containing newlines.
181 Use
182 .Xr find 1
183 .Fl print0
184 or similar if it's a concern.
185 .Pp
186 .Nm
187 .Cm mv
188 is not able to move directory trees, only file entries.
189 .Pp
190 There isn't an
191 .Cm init
192 sub-command, the store initialization must be performed manually.